May 2011
By Juergen Muthig

Juergen Muthig teaches technical communication with specialization in standardized document engineering at the Karlsruhe University of Applied  Sciences, Germany. He is also president of tekom.


juergen.muthig[at]hs-karlsruhe.de
www.tekom.de


 

Technical documentation needs standardization

Let's start with a white sheet of paper and a pen. Let's jot down some ideas. Let's start writing a manual. Let's do it on the computer with Microsoft Word. Letter by letter, word by word, sentence by sentence. Let's do it with a group of three, five, ten authors who write one chapter each. Let's move to FrameMaker, InDesign. Let's do XML. Let's use a content management system! What will be the outcome? How will the quality be? What about consistency? Cost? Translatability? Tech writers are expected to deliver a certain quality that cannot be met without standardization. But where do you start standardizing?

Is it really necessary to standardize when you are working by yourself and know what you are doing? Can't you be consistent and deliver good quality without applying standards? At the end of the day, all that matters is that users, customers and your boss are satisfied. But are they really?

Those writers who stay consistent in their document design and their writing, standardize intuitively possibly without calling it that. I am sure that all writers responsible for a print-ready document care about the layout, typography and the quality of writing. In order to achieve consistency they use formatting features like styles and autotext. Considerate writers will also structure text using headings, short paragraphs, lists and emphasize notes and safety messages. But do they do it consistently even in ONE document? And even more important: Would all writers in a group of five use the same structuring methods? Most likely not. In fact, we might have to write down the rules we will pledge ourselves and our co-authors to.
Creating a guideline for technical communication

Making up rules might become fairly random if you have no overview of all the aspects that are relevant for standardization. To start with, think about all the things a technical writer has to do in order to deliver a print-ready document. There is a lot more to standardize than the writing itself: There are the output media we write for, the software-tools we use, the rules for graphic material and screenshots, the whole documentation process, the people involved, their duties and responsibilities, the deliverables due at certain milestones etc.

We need a well-structured guideline that is more than just a style guide. But where do we start? It is true that developing such extensive guidelines can take months, if not years! But it does not have to be done all at once.

Potentially, everything that plays a role in developing technical documentation can be considered to become part of this guideline. But if we want to know where to start, my advice is the following: If you acknowledge that standardizing means defining rules that guarantee the desired degree of consistency on the desired level of quality, you should start with those topics that promise the best revenue with respect to quality and/or cost reduction.

Let's take a look at this advice more closely. First, the definition of standardizing states that rules guarantee consistency. But standardizing doesn't necessarily aim at absolute consistency. A corset that is too tight to breathe is lethal. Therefore, it is important to think about the adequate level to achieve the desired goals quality and cost-efficiency.
Finding adequate rules

Documentation quality is what the user wants, cost-efficiency is what your boss is primarily interested in. But consistency does not guarantee quality. If the rules are not good, you will receive consistent low-quality documentation. Thus, whoever is responsible for standardization needs to be a quality expert. Cost-efficiency is an easier-to-achieve result of standardization. With standardizing, e.g. the writing process can be sped up and translation costs can be reduced by up to 40 percent since the reuse of text in translation memory systems increases exponentially.

One of the key decisions in standardization is whether to go for an established standard or to use a standardization method to develop your own. Both have advantages and disadvantages. Established standards like DITA or DocBook are at least in theory ready to use and several software tools like FrameMaker already have a suitable Document Type Definition (DTD) implemented. The disadvantage is that a suit bought off the peg often doesn't fit well enough. This is the strength of methodologically developed company-specific standards.
Developing customized standards

Information Mapping, originally developed by Robert E. Horn, is one of those methods that are useful for developing standards for structured documents. The structural components are information blocks and information maps. The maps are put together by information blocks that belong to the six most common information types: Procedure, Process, Principle, Concept, Fact, and Structure.The use of the method is subject to licensing regulations.

Functional Design, developed by Robert Schäflein-Armbruster and Jürgen Muthig, has its roots in linguistics. Using the insights of the speech act theory, Functional Design became the leading method for developing standards for technical communication in Germany.

Let's take a look at some details to grasp the idea. How does the developer of a standard proceed according to the Functional Design method? The first step is to state the communicative goal the technical author wants to achieve. The second is to define which media and which didactical approach will be most promising to actually achieve the goal.

The third step is to define what speech acts will be most useful to achieve the communicative goal that needs to be accomplished with the information product. Speech acts are called Functional Units in the Functional Design method. Those Functional Units need to be defined as precisely as necessary to meet the consistency requirements. According to the Functional Design method, consistency-assuring rules can be defined in six categories: Usage, Content, Sequence, Wording, Design, and Marking.

In this third step most of the consistency-relevant rules are defined. It is vital that every single Functional Unit that is part of the standard is regulated according to these six categories. This guarantees that all authors perform their speech acts in the same way.

One of the prototypical Functional Units that is being used in all instructional manuals is 'making a request' or 'demand'. The author requests the user to turn a certain switch by saying Turn switch A to position STOP. For a simple request like this you need to make sure that all authors in your company handle requests the same way. If there are no regulations some might hide the request in descriptive text. Others might use different wording like A in STOP position. Others again might use bold face while you use standard type face and a numbered list for requests. There are always many possibilities for performing speech acts. If you want consistency you need to define which of these possibilites have to be ruled out and which are the ones to follow. Methodologically, the developer of a Functional Design standard will lay down the rules in guidelines according to the six categories.

There are more steps and aspects to the Functional Design method but this should suffice in order to realize that standardizing is not only necessary but can be done methodologically step-by-step.

And how does all this relate to standards like XML, Docbook or DITA? As established as the Darwin Information Typing Architecture an OASIS standard might be, if you are aiming at consistency in all six categories that have to be defined according to the Functional Design method, you need an authoring standard that provides all the necessary rules to achieve the desired quality.

No matter what you do as a technical writer, no matter where you work, if you want to handle the inherent complexity of technical documentation, you need to adopt useful standards and develop your own company standard, where the suit bought off the peg doesn't fit.