Bad advice: how to write technical documentation?

Tips for competently writing technical documentation for users.
Part 1

In a previous article, we outlined how the process of documenting and localizing our products takes place .

This time under the cut is the manual of our technical writer Andrei Starovoitov, which will help make your documentation easier and more user-friendly (the described techniques are used to document your products by Apple, Microsoft and other companies).

As you know, good documentation is not a luxury, but a means of increasing the company's sales. If you are going to start or are already developing some kind of program, then to enter the world market with it, you will need a user manual (aka User's Guide) or at least a document that tells customers how to start working with your product (the so-called Getting Started with).

In what language to write the documentation - in Russian, and then translate it, or immediately in English - you decide. At Parallels, we chose the second approach. It is often much easier to make a description in English, since almost all (and now we can say that "all") computer terms in Russian are borrowed.
Further in the text, we will focus on both Russian and English examples.

So what should you look for when writing documentation?

Types of topics in the documentation

When writing a topic, first you need to determine what kind of topic it will be :)

It will depend on this what and how to write in it.

There are 4 main types of topics :

• Topics that describe how to solve a specific task or several related tasks (in English this type of topic is called task pages) .

For example, “Install Parallels Desktop” or “Shut Down or Pause Windows.” Each of these topics describes a series of one or more steps that a user must take in order to achieve a specific goal. The user manual consists mainly of such topics.

Usually users do not like to read, especially when there is a lot of text. Therefore, you should try to make such topics as short as possible. Ideally, if the information is presented in the following form: “you can do something, just click here and here” (task topics will be discussed in more detail in the next part of the article).

If the developer believes that there is any additional information that the user needs to know about, and there is a lot of it, then this is best described in conceptual topics (see below).

• Conceptual topics (in English - concept pages ). In these topics there are no instructions on how to solve any problem. They contain information that rather contributes to a greater understanding of things. For example, conceptual topics are used to:

- Explain to users exactly how any process works;
- tell what can be done in the application settings;
- describe the added features in the new version of the product;
- provide additional information that will help the user better understand or solve a problem.

Please note that additional information (in case there is a lot of it) must be provided precisely in the conceptual topic so as not to overload the task topic.

• Reference topics (in English - reference pages) - contain information that the user can periodically refer to to find out what a particular term means, how a function works, etc. A good example of such topics is the dictionary at the end of the guide (aka Glossary). Reference topics are especially useful to explain the purpose of various interface elements.

• Topics that describe how to solve a problem (in English - troubleshooting pages ).

For example: “I cannot activate Parallels Desktop” or “I cannot connect to the Internet.” These topics describe what needs to be done to solve a problem. They may also contain information that will help to understand what is the cause of the malfunction.

Basic instructions for all types of documentation

When creating a guide:

1) Concentrate on the user

• Instead of structuring the product description on its features or interface elements, try to concentrate on the tasks that the user is most likely to try to solve.

For example, a topic on how to protect data in a virtual machine can be named in 2 ways:

a) “Security Settings”, where you can describe in detail what can be done to protect data.

b) Make several topics describing specific tasks:

- “Protect Your Data with Antivirus Software”

- “Make a backup of your virtual machine” (“Back Up Your Virtual Machine”)

According to current trends in documentation, the second approach is preferable, since in this case the user does not have to guess whether or not to do something, and he receives clear instructions on what exactly needs to be done.

• Focus on the tasks of the user and his level of technical literacy.

For example, in the documentation for the average user, instead of writing “Create a Virtual Machine”, you should write “Install Windows or any Other OS”, as the term “ virtual machine ”is far from known to everyone. Or another example - a topic that describes how to create quick keyboard shortcuts, it is better to call “Configure Keyboard Shortcuts” rather than “Keyboard Settings”.

Although what’s the point, to the majority of Habr’s readers it would be clearer to “Configure shortcuts”, but the question is already how much such a term is appropriate in official terminology at this time :)

• If this may not be clear, explain why the user may need to perform a particular task.

For example:



• When describing, try to use those words that the user uses every day in his speech. If a technically complex term can be replaced with simpler words, always try to use simpler words.

For example, “transparent” instead of “transparent”. If you give an example from the English language, then use "use" instead of "utilize".

2) Try to give all the necessary information without unnecessary words

“Ambassadors from the island of Samos came to Sparta to ask for help. They made a long and beautiful speech. The Spartans said: "Having listened to the end, we forgot the beginning, and forgetting the beginning, we did not understand the end." Samosets were quick-witted. The next day, they came to the meeting with an empty bag and said only four words: "There is a bag, there is no flour." The Spartans scolded them - two words were enough: "there is no flour," but they were pleased with such quick wits and promised to help. "

If you describe the functionality too long - no one will read it. But it’s completely “in Spartan” way too, because if too little is written there will be questions and doubts, users will start to pull the support team. In general, it is important to maintain balance.

To help users find all the information they need and at the same time describe each section as briefly as possible:

• Focus on the most important information that is needed to solve the problem described in the topic. If some details are not necessary for the task, do not describe them.
• No need to document every click. If everything is clear in the interface, let the user figure it out himself. For example, instead of documenting each step of the program installation, it is better to write: “In order to install the program, follow the instructions on the screen.” If, as the last stage of a procedure, you must click OK, this is also not worth describing.
• Instead of giving all the information in one topic, show the user where you can read additional information using links to other topics, links to external resources, or insert at the end the “Related Information” section, which will contain links to topics related to what is described on the screen.
• If a long task can be divided into several stages or subtasks, each of which is a separate task, break the topic into the appropriate sections or create a section in the guide, consisting of topics that describe each stage. In this case, do not forget to insert links to related topics.
• If a task (for example, starting a virtual machine) can be performed in several ways, there is no need to describe them all. Suffice it to mention the fastest and easiest way. If you still think that it is useful for the user to know about any other method, describe it in the end (in English - Outro) topic.

3) Do not repeat the same information on the pages.

Instead of repeating information in each topic that is already described in some other topic, it’s better to refer that a more detailed description can be found in such a topic, or just give its a hyperlink.

4) Attract the user's attention correctly

When the description needs to attract the user's attention, the following introductory words are used - “Attention!” (In English - Warning!), “Important:” (in English - Important :) and “Note:” ( in English - Note :).

Each of these words implies its own level of "importance."

In order not to strain the user in vain, use each term correctly:

• Use “Caution!” (Warning in English) to indicate a dangerous situation which, if not avoided, could result in data loss, component damage, or any other damage.
• Use "Important:" (in English - Important :) to indicate a significant and potentially problematic situation, which, however, cannot lead to physical damage, damage or data loss.
• Use “Note:” (Note :) to provide any additional information related to this topic. Although such an insertion detaches users from the current task, it can be useful.

For example:

To open the virtual machine configuration, click Actions> Configure.
Note: The virtual machine must be turned off.

Use the note “Note:” sparingly - if you insert it too often, it clogs the text, and it stops paying attention to it.

If possible, insert “Attention!”, “Important:” and “Note:” at the beginning of the topic so that the user finds out about this before starting to perform any procedure. However, if the information only refers to a particular step, insert it after this step.

Example:



To be continued ...

(in the next part of the article we will discuss in more detail topics that describe how to solve a specific problem)