7 rules for writing world-class technical documentation

Introduction

Writing a technical document is difficult. Reading a poorly written technical document is more difficult and probably more painful than writing it. It takes a lot of work to create a clear, accurate, interesting technical description. Therefore, in order to make life a little easier for all parties involved, I would like to share with you the family rules that I follow when creating technical documentation.

These rules are not my own invention. Rather, I simply formulated them from the experience that has emerged due to communication with many talented technical and literary editors for more than ten years of work. Everything that I understood in this matter was formed because others showed me the way. I don’t have enough words to express my full gratitude to them.

I hope after reading this article some new tools will appear in your arsenal to help you create technical documents at a new level of quality: clearer, more attractive, less confusing and much more interesting to read. I also added - without any additional requirements for you, as a consumer, a bonus at the end of the article: a description of the process I use to create a technical description.
')
So - these 7 rules:

1. Boredom kills
2. Before you begin, find out for yourself exactly what actions you expect from a reader who has mastered your work.
3. Write in accordance with a well-formed structure.
4. Avoid ambiguous pronouns
5. Clarity = illustration + words
6. When dealing with concepts, concepts, etc., use a logical illustration and example.
7. Do not be afraid of alterations

1. Boredom kills

This rule seems to be the most difficult to formalize and the most important when it comes to compliance. In the modern world of the Internet there are a lot of forces fighting for the attention of your reader. A boring standard description will not work. Under any circumstances, your reader wants to be fun and informative. Therefore, if your text is unclear or uninteresting, the reader will simply click the notorious “Next” button and go to another web page or to another TV program or to your Facebook page.

The easiest way that I found to awaken interest in the reader is to make it interesting for me. I always make significant efforts to write such an article that I would like to read. I strive to enjoy what I write. If I'm bored, then the reader will be bored. If I'm confused, the reader will be confused. If I do not care about the topic in question, then the reader, moreover, will not be excited. Everything is very simple!

I like humor, so I try to make my literary technical “creations” amusing, but, of course, without compromising clarity. Trying to talk to the reader, and not to teach him. I am writing about matters that really matter to me. I use illustrations extensively to prevent confusion for the reader.

And again, I always try to make the reading process fascinating. I always remember what I write in a competitive environment. There are many content that seeks to attract the attention of readers. Thus, my advice on rule number 1: if your texts are of interest to you, they will be interesting for the reader.

2. Before you begin, find out for yourself exactly what actions you expect from the reader who has mastered your work.

Technical documentation is completely tied to the subsequent behavior of the reader. The reader spends his time reading your creation, because he or she has the intention to do something after the reading process is completed. This “something” can be baking cookies with chocolate pieces , stopping a nuclear reactor or developing a Hadoop cluster . It is important to remember that the reader uses your description as a means to perform another process. Your work is a kind of guide to further well-defined behavior.

Therefore, it is extremely useful for you to clearly define what actions you expect from the reader after the completion of the reading process. State your intention from the beginning. Do not leave the reader to guess. Your statement may be simple and obvious, like, for example: “after reading this article, you can [enter your version].” If you have decided on the actions expected from the reader after reading, then the writing process will be easier for you from the very beginning.

3. Write in accordance with a well-formed structure.

A well-formed structure is the skeleton around which your document grows. Preparing a technical document without using some structure is tantamount to trying to navigate the New York subway (469 stations!) Without a scheme. You may be anywhere, but this “anywhere” may not be the place you were supposed to go.

Writing technical documentation in accordance with the structure does not mean an increase in the amount of work. On the contrary, the load decreases. Working with the structure, you know where you are going from and where you are going to come.

There are two structuring rules that I always use:

1. The sublevel section requires at least one position.
2. At each level of the structure there should be at least two sentences.

I would like to clarify. Listing 1 at the bottom is an example of a structure that violates the first rule: a sublevel section requires at least one position .

Listing 1: malformed structure

1. Cooking orange-cranberry-tangerine fizzy drink

1.1. Steps required for making effervescent beverage

1.1.1. Ingredients preparation

1.1.2. Mixing Effervescent Drink Ingredients

1.1.3. Effervescent Serving

Notice that in Listing 1, Level 1 has a single sublevel: " 1.1. Steps required to make a fizzy beverage ." Such a structure is a violation of the first rule. For a sublevel to be properly formed, there must be at least one more position in the section. In other words, this means that at any given level there must be at least two sublevels.

See listing 2 below. Please note that level 1 now has three sublevels, of which the “Mixing Effervescent Ingredients” section contains positions. The single level “Steps required to make a fizzy drink” has been removed.

The question may arise: “Where is the section Steps required for making a fizzy beverage ? ” It can be seen that this section is no longer the position of the structure, but has moved to the content of the original section, as shown in Listing 2 below.

Listing 2: a well-formed structure that violates the two-sentence rule

1. Cooking orange-cranberry-tangerine fizzy drink

The section below describes the process that must be followed to make an orange-cranberry-tangerine fizzy beverage.

1.1. Ingredients preparation

1.2. Mixing Effervescent Drink Ingredients

1.3. Effervescent Serving

Notice that, while Listing 2 shows a structure with a well-formed sublayer, there is only one sentence in the content of the level 1 section. The presence of one single sentence in the content of the structure section violates the second structuring rule - “ At each level of the structure there should be at least two sentences ”.

Listing 3 shows the same text, but modified to ensure that the two-sentence rule is met.

Listing 3: well-formed structure that executes the two-sentence rule

1. Preparation of effervescent orange-cranberry-mandarin beverage

Orange-cranberry-mandarin fizzy drink can be a great pleasure on a hot summer day. The drink consists of natural ingredients without artificial flavors. Orange-Cranberry-Tangerine Fizzy Drink is not only delicious, but also extremely healthy!

The sections below describe the process that must be followed to make an orange-cranberry-tangerine fizzy beverage.

1.1. Ingredients preparation

1.2. Mixing Effervescent Drink Ingredients

1.3. Effervescent Serving

Why am I so worried about the right structure and at least two sentences at each level? First, the observance of the sublevel rule prompts me to be extremely clear in the logical segmentation of my work. Adherence to the sublevel rule also contributes to the fact that my text connects my ideas with a common line, which makes sense and is easy to trace.

Secondly, the rule of two sentences requires me to write a text that is attractive, detailed and expedient. When writing to the "one sentence" is often lost details. And, if one does not consider aphorisms, the text in “one sentence” is not the most interesting reading.

4. Avoid ambiguous pronouns.

Ambiguous use of pronouns is probably the most common cause of confusion in the practice of preparing technical descriptions.

Consider the paragraph in Listing 4.

Listing 4: ambiguous pronoun paragraph

Trafalgabory is the base component of the Vibitate frame. This article shows what they are and how to use them.

This paragraph may look somewhat comical, but it illustrates some important points. First, the paragraph tries to put you in the place that the reader takes. The reader wants to understand what is happening, but he is unfamiliar with the terms used. And since the terms are incomprehensible, the reader feels incompetent and therefore vulnerable. The reader needs new information - he or she wants to become smarter. But the reader is also a little worried. Admitting his own incompetence, even in front of himself, even on a subconscious level, can be unpleasant for him. The reader is painfully sensitive to understanding the material presented. The concepts and words that you, the person writing, take for granted, may be completely alien to the reader. One poorly explained concept or one word, used without proper explanation, can push the reader to stop reading.

As applied to the paragraph above, I would not be surprised if you ask: “What is this“ Trafalgabor ”thing? What is “Vibitata”? What, in general, is this paragraph? How to use trafalgabory? Or how to use vibrates? Or how to use both? This makes no sense. I’ll be back better on my Facebook page. ”

If the reader, while reading your description, is forced to spend time figuring out what you are trying to tell him, not only will the informative stream be broken, but the reader will most likely be confused. As soon as you confused the reader, you lost him. Everything else in the world, aimed at attracting the attention of your reader, becomes more attractive to him than your creation. Clicking the "Next" button - and your work remains unread.

In Listing 4, confusion is caused by the ambiguous use of the pronoun "they" in the second sentence. What does “they” refer to here - to Trafalborams, Vibitates or to both? Remember that the reader does not know anything, what is Trafalgabory or Vibitata. (See Figure 1 below.)


Fig. 1. The use of ambiguous pronouns confuses the technical description

The solution is simple. See listing 5 below. Ambiguous pronoun removed. Clarity restored.

Listing 5: Removing ambiguous pronouns

Trafalgabory is the base component of the Vibitate frame. This article tells you what Trafalgabori is and how to use it.

Caution! Ambiguous use of pronouns leads to a technical description, confusing.

5. Clarity = illustrations + words

Look at the photo below. Tell me, if you can, what is this photo about?



I would not be surprised if you are a little confused. This photo is really puzzling. You know all the individual components, but you are unclear what they all mean together. Such is the nature of any illustration. The picture without words lacks context.

When referring to illustrations, readers need context to clarify. It is unacceptable for the reader to waste time or effort trying to figure out what the graphics in question are about. The easiest way to eliminate the ambiguity with the illustrations is to provide them with inscriptions.

Look at the pic. 2 below. It represents the same photo. But there is no question what it is.


Fig. 2. Tools and ingredients required for making orange-cranberry-tangerine fizzy drink

With regard to technical descriptions, I find it useful to provide all the illustrations with numbered descriptive inscriptions.

Do not put labels that contain only numbers. Use both numbers and descriptive comments in the caption. Also do not allow the appearance of isolated illustrations. The isolated illustration is considered such which is located in the technical specification, but the link to which in the text is absent.

When inserting an illustration into your description, make sure to refer to it in the text by indicating its number and such words as “above,” “above,” “below,” “below.” It is unacceptable to force the reader, while reading your work, to spend time binding the illustration to the text or searching for it in the description. If you add to the text, say, “Pic. 4 ", then make sure that somewhere in the text says something like" see rice 4 below.

Note : eye attract images

Ten years ago, I worked in a group that wrote a user manual (for printing) for a very, very large computer manufacturer. All manuals were subject to formal quantitative research on usability. Then I learned from the user interaction specialists that when a person reads the manual, his eye goes first to the images. Only then does the reader look at the text around this image. Therefore, the authors of this manual tried to ensure that on each page there was at least one picture.

6. When dealing with concepts, concepts, etc., use a logical illustration and example, a logical illustration and example

Concepts are difficult to understand - and this is why they are called "concepts." Therefore, when I have to write about a general situation, be it the second law of thermodynamics , a component of a coding technique, or a full-featured software platform, I use the following approach in my description: the concept — logical illustration — is an example. I never try to introduce any concept without reinforcement with logical illustration and further example.

We apply this rule to describe the concept of elementary algebra.

The concept of "transitivity of the equality relation" is as follows:

if A = B and B = C, then A = C;

Now we give a logical illustration describing this concept (see Fig. 3).


Fig. 3. The transitivity of the equality relation is the fundamental principle of elementary algebra

Listing 6 below shows some concrete examples to reinforce an understanding of the situation in question.

Listing 6: Some specific examples of equality transitivity

• If 7 = 3 + 4 and 3 + 4 = 5 + 2, then 7 = 5 + 2;
• If 12 + 5 = 7 + 10 and 7 + 10 = 6 + 11, then 12 + 5 = 6 + 11;
• If x + y = z and z = 2a, then x + y = 2a.

Thus, the rule is observed. We introduced the concept of “transitivity of an equality relationship”, illustrated it with a descriptive drawing and supported it with examples.

Now consider a concept that is closer to software development and somewhat more difficult to understand. Such a concept is the inheritance of project object models (POM = Project Object Model) in Maven (an automated project assembly system). Example 1 below represents the concept under consideration and provides a logical illustration describing this concept. At the end there is another illustration showing the specific use of POM files in the inheritance situation.

Example 1: excerpt from the technical description of the inheritance of project object models (POM) in Maven (automated project assembly system)

POM file inheritance view

A POM file is an XML file used to describe the Maven project and to work with this project. You can specify that some Maven project inherit settings from a separate parent POM file. The ability to inherit settings from the parent POM file is called POM inheritance. You are using an item

<parent> 

in your POM file to set the parent POM file from which the settings should be inherited.

Fig. 4 below shows the hierarchy of some conditional project, which is an example of setting the master ROM file, from which other ROM files can inherit the general settings.


Fig. 4. You can assign a master ROM file from which the general settings will be inherited

Fig. 5 below shows the contents of the POM.xml files for the stooges-web, stooges-api and stooges-dal Maven projects. Each project is configured to use an item.

 <parent> 

to inherit settings from stooges-project.


Fig. 5. Use item

 <parent> 

to manage a Maven project in order to inherit settings from an external ROM file

The example above relies mainly on the figures to provide a logical illustration and to show the specific use of the concept in question. Preparing interesting, attractive and accurate illustrations and examples is a difficult task, but the effort is worth it. Creating a set of illustrations for technical text and code samples takes no less time than writing the text itself. Accordingly, I plan my time to complete the work on time.

So, if it is required to clearly present some concept, then it is necessary to include illustrations and examples in the text.

7. Do not be afraid of alterations

It is rarely possible to write a good technical text on the first attempt. Mastering the topic, organizing approaches and finding a form for a clear and accurate presentation of ideas requires a lot of time and effort. So don't be shy about expecting everything to work out right the first time. Better plan to go through at least three versions of your creation. The first version is just a certain set of words in printed form, giving you the opportunity to realize your intentions. The second version already gives your work clarity and accuracy. Then, when all the facts in the text are verified, the illustrations are verified and the structure is logically aligned, you can prepare a third version that will be attractive and unique.

We can say about this work, paraphrasing Thomas Edison's famous quotation : “Writing a technical text is 10% literary work and 90% recycling!”

Promised Bonus

Now that you know the 7 rules for creating world-class technical documentation, I would like to share with you a summary of the process that I use in preparing technical texts. Here it is a little, but in essence. I call this process “7 steps to create a technical document . ” So:

1. I make a structure, at least to the second level (if it is possible, then to the third);
2. Add illustrations to the structure for each concept;
3. I make signatures under the illustrations;
4. I write the text in accordance with the structure, observing the rule of two sentences and adjusting the structure to the text;
5. Edit, rework;
6. I send the result to a specialist on the topic under consideration for reviewing (a specialist on the topic under consideration is a person who is able to identify inaccuracies and ambiguities in the description);
7. Again I edit the work based on the reviewer's review (s).

And here you are: 7 rules, 7 steps. Does someone need more? Now that you know all my techniques, move forward freely and make the world a better, more attractive, clear and interesting place to live. He deserves such an effort.