Bad advice: how to write technical documentation?

Tips on writing competent technical documentation for users.
Part 1

In one of the previous articles, we outlined in general terms how the process of documenting and localizing our products proceeds.

This time under the cut - the guidance of our technical writer Andrei Starovoytov, which will help make your documentation for users easier and more understandable (the described techniques are used in documenting their products, 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 any program, in order to enter the world market with it, you will need a user manual (the same as User's Guide) or at least a document that tells customers how to start working with your product (so-called Getting Started with).

In what language to write documentation - in Russian, and then translate it, or immediately in English - you decide. At Parallels, we chose a second approach. It is often much easier to make the description in English, since almost all (and now we can say that “all”) computer terms in Russian are borrowed.
Further on, 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 it will be for the topic :)

From this will depend on 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 "Turn off or pause Windows." Each of these topics describes a series of one or more steps that the user must take in order to achieve a specific goal. The user's 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 this form: “you can do this, for this, click here and here” (the task topics will be discussed in more detail in the next part of the article).

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

• Conceptual topics (in English - concept pages ). In such topics there are no instructions 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 how exactly a 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 to better understand or solve any problem.

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

• Reference topics (in English - reference pages ) - contain information to which the user can periodically refer 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 the various interface elements.

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

For example: "I can not activate Parallels Desktop" or "I can not 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 the reason for the malfunction.

Basic instructions for all types of documentation

When creating a guide:

1) Concentrate on 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 called in two ways:

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

b) Make several topics describing specific tasks:

- “Protect your data with antivirus” (“Protect Your Data with Antivirus Software”)

- “Back up your virtual machine” (“Back Up Your Virtual Machine”)

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

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

For example, in the documentation for a regular user, instead of writing “Create a Virtual Machine” you should write “Install Windows or another operating system” (“Install Windows or any Other OS”), since the term “ virtual machine "is not known to everyone. Or another example is a topic, which describes how to create quick keyboard shortcuts on the keyboard, it is better to call “Configure Keyboard Shortcuts” rather than “Keyboard Settings”.

Although something to prevaricate, the majority of Habr's readers would understand “Set up shortcuts,” but the question is how relevant the term is appropriate in the official terminology at this time :)

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

For example:



• When describing, try to use the words that the user uses every day in his speech. If a technically difficult term can be replaced by 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 further ado.

“Ambassadors from the island of Samos came to Sparta to ask for help. They delivered a long and beautiful speech. The Spartans said: “Having listened to the end, we forgot the beginning, and having forgotten the beginning, we did not understand the end.” The samostsy were shrewd. 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 - it was enough two words: "there is no agony," but they were pleased with such ingenuity and promised to help. "

If you describe the functionality too long - no one will read it. But absolutely “in Spartan” will not work either, because if it is written too little, there will be questions and doubts left, users will start pulling the support team. In general, it is important to maintain a balance.

To help users find all the necessary information and at the same time describe each section as short as possible:

• Focus on the most important information that is needed to solve the problem described in the topic. If some parts are not necessary to complete the task, do not describe them.
• No need to document every click. If the interface is clear, let the user figure it out for himself. For example, instead of documenting each step of the installation program, it is better to write: "In order to install the program, follow the instructions on the screen." If, as the last step of any procedure, you have to press the OK button, 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 at the end insert the section "Related Information" (Related Topics), which will link 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 appropriate sections or create a section in the guide consisting of topics describing each stage. In this case, do not forget to insert links to related topics.
• If you can perform a task (for example, start a virtual machine) in several ways, there is no need to describe them all. It will be enough 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 that is already described in some other topic in each topic, it’s better to refer to a more detailed description in such a topic, or just give a hyperlink to it.

4) Get the user's attention right

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 “Warning!” (In English - Warning!) To indicate a dangerous situation, which, if not avoided, can lead to data loss, damage to components or any other damage.
• Use "Important:" (in English - Important :) to indicate a significant and potentially problematic situation, which, however, can not cause physical damage, damage or data loss.
• Use "Note:" (in English - Note :) to provide any additional information related to this topic. Although such an insert and tears users from the current task, but it can be useful.

For example:

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

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

If possible, insert “Attention!”, “Important:” and “Note:” at the beginning of the topic, so that the user will know about it before he begins to perform any procedure. However, if the information relates only to a specific step, insert them after this step.

Example:



To be continued…

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