Bad advice: how to write technical documentation? Part two
Tips for competently writing technical documentation for users.
Part 2
Continuation of the manual of our technical writer Andrei Starovoitov, which will help make your user documentation easier and more understandable.
You can read the beginning of the article here , but we described the process of documenting and localizing our products earlier in this article .
In this part, we will analyze in detail the topics that mainly consist of user documentation (especially the User's Guide) - namely, task topics that describe how to solve a specific problem.
How many tasks to describe in the topic - one or more?
A task topic can describe both one task - “Launch a Windows Application” (“Launch a Windows Application”), as well as several related tasks. For example, the “Optimize Performance” topic may consist of the following sections: “Automatically Conserve Disk Space” and “Tune Your MacBook to Better Performance or Save Battery” (“Optimize Your MacBook for Longer Battery Life or Higher Performance ”).
We should try to write task topics on the principle: one topic - one task. True, there is an exception - if you have two tasks that are opposite in action, then they should be described in one topic. For example, if you need to describe how to switch the virtual machine to full-screen mode and how to exit it later, you need to do this within the same topic.
If you need to describe several related tasks, then this can also be done in one topic, provided that their description is not long.
Sections of task topics
Task topics consist of:
Sometimes it happens that the task topic does not contain all of the above sections - for example, there is no need to insert Intro or Outro. Further we will dwell in more detail on each section of the topic.
Heading
We must try to make such headings so that the user immediately understands what will be written in the topic.
Make headlines capacious, but not too long at the same time. Long headers may not be fully displayed in some browsers or the Apple Help Viewer.
When writing header imperative use ( "Do-so")
For example, " Adjust printer via Bonjour " ( "Set Up a Printer Using Bonjour").
Do not use the imperative in the names of topics that do not describe how to solve a problem.
В названии топика используйте понятные пользователю слова, не концентрируйтесь на элементах интерфейса.
Пользователю не хочется разбираться в фичах, терминах, элементах интерфейса итд — ему надо решить свою конкретную задачу. Поэтому в названии топика старайтесь использовать те слова, которые употребил бы сам пользователь. Например, если назвать топик «Подготовьте Mac к использованию Windows приложений» (“Set Up Your Mac to Use Windows Applications”), то это будет намного понятнее для пользователя, чем топик «О виртуальных машинах» (“About Virtual Machines”).
Старайтесь формулировать цель так, как это, вероятно, сделал бы сам пользователь. Например, вместо «Начните удаленную сессию» (“Start a Remote Session”) — лучше назовите топик «Start working remotely with Windows ”(“ Start Controlling Windows Remotely ”).
If you need to use technically complex terms or interface names, then this is best done not in the header, but in the introduction of the topic.
If you are writing documentation in English, the words in the title should begin with a capital letter.
Correct : Set Up Your Mac to Use Windows Applications
Incorrect : Set up your Mac to use Windows applications
(we will discuss the capitalization of the header in the next part of the manual in more detail).
Introductory part (Intro)
In the introductory part, which goes immediately after the heading, you should write what the user needs to know before he begins to complete the task.
The prologue may contain:
Use ready-made virtual machines
If you do not have time to create a new virtual machine with the necessary configuration, you can download a ready-made virtual machine with a pre-configured configuration.
For example, if a Parallels Desktop user wants to work with macOS and Windows at the same time as if it were a single operating system, then in the introductory part you can talk about “Coherence mode” in order to prepare the user for terms that will be further used in the topic.
Do not insert the introductory part where it is not necessary.
Although the introductory part provides additional useful information, sometimes everything is clear from the heading itself. In such cases, you do not need to come up with an introductory text, if only it were.
For example:
Launch Mac applications through the Start menu.
Open the Windows Start menu and do one of the following:
Do not make the prologue too long. The
prologue is too long annoying the user. In such cases, users often skip it and go straight to the list of specific steps.
If the introductory part is too large, you need to mention the main one and give a link to a separate conceptual page or reference page, in which everything will already be described in detail.
Sometimes, to visually facilitate reading of long text in the introductory part, bullets can be used. For example:
Do not tell in the introductory part how to complete the task. The
introductory part is not for this. What needs to be done, where and how - it is necessary to describe only later, after the introductory part.
However, in rare cases, you may need to tell users what they need to complete the task. In the example below, the introductory part tells users what they need to complete the task described in the topic.
Do not describe the results of the task in the introductory part.
This should be done in the final part ( Outro ).
The phrase before the instructions (Step Heading)
After the Intro, you must insert the "introductory" phrase (in English - "step heading"), which leads the user to the instructions: what exactly needs to be done to achieve a particular result.
For example, in Intro we write: “ If you have an installation disk and an activation key, you can use them to install Windows in a virtual machine. "
After Intro comes step heading: “ To install Windows: ”
And then the steps themselves:
1) Click here.
2) Choose this.
3) And so on ...
Note: if there is no Intro in the topic, then step heading is optional.
If the topic describes sequential steps, then step heading should look like “ To do something:” (“To do X:”).
For example: " To run the Windows:» ( "the To start the Windows:") or " To switch to full screen mode:» ( "the To switch statement to of Full Screen mode:").
Do not forget to put a colon at the end
If the heading uses user-friendly words, and you have to use complex technical terms or names of the interface elements in the instructions, you can do the following: in the introductory part you explain what the term means, and in step heading you already use it actively.
For example:
1) do poponyatnee header for the user:
"Run Windows in full screen» ( "the Set of Take Windows to the Up the Whole Screen")
2) The following Intro introduce the term "full-screen mode» ( "of Full Screen mode").
3) After this, you can use the term in step heading without fearing that it will not be understandable to the user:
“To enter full screen mode:” (“To enter Full Screen:”)
If the steps described in the topic are not a sequence of actions, but several ways to achieve the goal, then step heading should be done as follows: “Here are some ways to do something:” (“Here are ways to do X:”) or “ To do this, do one of the following: ” (“ To do X, do one of the following: ”).
For example, " Here are some ways on how to disable the Windows: » ( "Here are ways to shut down the Windows:") or " To connect the printer, do one of the following: » ( "the To the connect a printer, do one's of the the following: ”).
When creating step heading, you need to use those words that reflect the task described in the task topic. Here are some examples in English:
Page Title : Install Windows from an Installation Disc.
Task Covers : Installing Windows using an installation disc.
Step Heading : To install Windows.
Page Title : Adjust Coherence Settings.
Task Covers : Customizing how Windows appears and behaves in Coherence mode.
Step Heading: To customize Coherence mode.
Page Title : Set Windows to Take Up the Whole Screen
Task Covers : Entering full screen mode.
Step Heading : To enter Full Screen mode, do one of the following:
Numbered Steps
All topics that describe how to perform a particular task contain instructions on what to do. These actions in the text are usually either numbered (if it is a series of consecutive steps) or highlighted by bullets (if it is proposed to choose one of the list at your discretion).
Keep the list of necessary steps as short as possible.
Choose and describe the easiest and fastest way to perform an action. Alternative methods can be described in the final part (Outro) or in another task topic. Do not force the user to read the instructions in 4 steps, if all the same can be done by clicking on one button.
If the easiest way is to perform the action through the toolbar, describe this option. If the toolbar can be customized to your liking, and you have doubts, suddenly the user’s configuration of the toolbar differs from that described in the topic, describe everything as it is done with the default settings. As practice shows, most ordinary users rarely change the "factory" settings.
If you need to describe several ways how to perform an action in one topic :
If in many task topics of your book a certain action is repeated that can be performed in different ways (say, through a menu or toolbar), select one method and mention it sequentially in each task topic.
Если же есть простой и короткий альтернативный способ, и вы непременно хотите о нем рассказать, можно сделать это в том же шаге.
Например: «Чтобы открыть настройки виртуальной машины, нажмите Действия > Настройки или кликните иконку Настроить в правом верхнем углу» (“To open the virtual machine configuration, choose Actions > Configure or click the Configure icon in the top right corner.”).
Последовательно нумеруйте шаги, которые надо выполнить
Чтобы не раздувать описание и не выделять очень короткие инструкции в отдельные шаги (типа «Нажмите OK»), можно комбинировать 2 близких и связанных действия в один шаг, как показано ниже:
Используйте буллиты для выделения непоследовательных действий
Sometimes the user is offered several ways to choose how to achieve the goal. In such cases, the proposed options emit bullets.
For example:
If the names of graphic elements are in the list, highlight them in bold for clarity.
If the action that the user needs to do is list a number of graphical interface elements (menu items, daws, etc.), start each option from a new line, highlighting item name in bold. After the element marked in bold, put a colon and then explain the description in plain text.
As shown in this example:
If the text in the topic refers to various interface elements many times, it may be worth creating a separate help topic in which these elements will be described.
This will be especially useful if many topics in the guide refer to the same elements. In this case, at the beginning of the topic, you must give a link to the reference topic in which the mentioned element is explained.
If this element is mentioned again later in the text, you no longer need to give a link to it - just one at the beginning. When there are a lot of links in the topic, this can complicate the perception and understanding of what is written.
The final part (Outro)
Outro is the final information that comes after the numbered steps. Try to make the final part shorter - use no more than 3 paragraphs, each of which consists of a maximum of 3 sentences.
Use Outro to describe the results or consequences of these actions.
An example of a result or consequences can be:
• Information about where any files were installed;
• A message appears that will require additional actions from the user;
• Settings that the user will need to switch after the described actions have been completed.
For example, the final part of the topic on how to make Parallels Access work only on Wi-Fi, says the following: “ If you configured Parallels Access to work only on Wi-Fi and no wireless networks are currently detected, a message appears asking you - Would you like to connect via 3G? ".
In the final part of the topic, you can describe an alternative way to complete the task.
If the alternative method can be described in one sentence, you can do this in the final part of the topic.
Outro can provide more information that pertains to the current task.
Such information can inform users about what else they can do after completing the described task.
In the following example, the topic describes how to find a file from a virtual machine in macOS Finder. And in the final part of the topic describes what else the user can do with the file after the file is found.
In Outro, you can describe additional information that only some users will need.
For example, in the final part of the topic about integrating Windows virtual machines into macOS, you can write the following:“If you have a MacBook Pro 2016 or later, you can work with some Windows applications using the Touch Bar”
Break up long tasks into short steps
Basically, task topics are short and fit on one page. However, if some complex and very long task is described, which can be divided into stages, stages and procedures, it is worth logically separating the information and describing each stage in a separate topic so that the description looks simpler, better read and understood.
The following is an example from the contents of the Parallels Desktop User's Guide. The screenshot shows a chapter that describes various ways to install Windows in a virtual machine. And one of the ways - how to import data from a remote computer - is divided into several topics.
To be continued ...
(in the next part we will talk more about conceptual and reference topics and topics that help solve problems)
Part 2
Continuation of the manual of our technical writer Andrei Starovoitov, which will help make your user documentation easier and more understandable.
You can read the beginning of the article here , but we described the process of documenting and localizing our products earlier in this article .
In this part, we will analyze in detail the topics that mainly consist of user documentation (especially the User's Guide) - namely, task topics that describe how to solve a specific problem.
How many tasks to describe in the topic - one or more?
A task topic can describe both one task - “Launch a Windows Application” (“Launch a Windows Application”), as well as several related tasks. For example, the “Optimize Performance” topic may consist of the following sections: “Automatically Conserve Disk Space” and “Tune Your MacBook to Better Performance or Save Battery” (“Optimize Your MacBook for Longer Battery Life or Higher Performance ”).
We should try to write task topics on the principle: one topic - one task. True, there is an exception - if you have two tasks that are opposite in action, then they should be described in one topic. For example, if you need to describe how to switch the virtual machine to full-screen mode and how to exit it later, you need to do this within the same topic.
If you need to describe several related tasks, then this can also be done in one topic, provided that their description is not long.
Sections of task topics
Task topics consist of:
- Heading
- Introductory part (in English “intro”)
- Phrases, which leads to a description of what exactly the user needs to do (in English “step heading”)
- Numbered or starting at a large point steps (in English “numbered or bulleted steps”)
- The final part (in English “outro”)
Sometimes it happens that the task topic does not contain all of the above sections - for example, there is no need to insert Intro or Outro. Further we will dwell in more detail on each section of the topic.
Heading
We must try to make such headings so that the user immediately understands what will be written in the topic.
Make headlines capacious, but not too long at the same time. Long headers may not be fully displayed in some browsers or the Apple Help Viewer.
When writing header imperative use ( "Do-so")
For example, " Adjust printer via Bonjour " ( "Set Up a Printer Using Bonjour").
Do not use the imperative in the names of topics that do not describe how to solve a problem.
В названии топика используйте понятные пользователю слова, не концентрируйтесь на элементах интерфейса.
Пользователю не хочется разбираться в фичах, терминах, элементах интерфейса итд — ему надо решить свою конкретную задачу. Поэтому в названии топика старайтесь использовать те слова, которые употребил бы сам пользователь. Например, если назвать топик «Подготовьте Mac к использованию Windows приложений» (“Set Up Your Mac to Use Windows Applications”), то это будет намного понятнее для пользователя, чем топик «О виртуальных машинах» (“About Virtual Machines”).
Старайтесь формулировать цель так, как это, вероятно, сделал бы сам пользователь. Например, вместо «Начните удаленную сессию» (“Start a Remote Session”) — лучше назовите топик «Start working remotely with Windows ”(“ Start Controlling Windows Remotely ”).
If you need to use technically complex terms or interface names, then this is best done not in the header, but in the introduction of the topic.
If you are writing documentation in English, the words in the title should begin with a capital letter.
Correct : Set Up Your Mac to Use Windows Applications
Incorrect : Set up your Mac to use Windows applications
(we will discuss the capitalization of the header in the next part of the manual in more detail).
Introductory part (Intro)
In the introductory part, which goes immediately after the heading, you should write what the user needs to know before he begins to complete the task.
The prologue may contain:
- Additional general information: what the user can do.
- Motivation : why the user may need to perform one or another action. Here is an example introductory part that describes why you might need to download and use ready-made virtual machines:
Use ready-made virtual machines
If you do not have time to create a new virtual machine with the necessary configuration, you can download a ready-made virtual machine with a pre-configured configuration.
- Warnings (Warnings) of any possible damage to equipment, software or data loss that may occur while the user performs some action.
- Important information about potential problems or difficulties that, although they do not result in damage to health, equipment, or loss of data, may occur during the execution of a task.
- Explanation: what does this or that term mean or how does any feature work.
For example, if a Parallels Desktop user wants to work with macOS and Windows at the same time as if it were a single operating system, then in the introductory part you can talk about “Coherence mode” in order to prepare the user for terms that will be further used in the topic.
- Information about additional conditions : for example, in the topic that describes how to connect the printer via Bonjour, the intro may inform you which versions of Windows support Bonjour.
- Conditions necessary for the current task : if before starting to perform the tasks described in the topic, the user needs to do or check something else, then this should be mentioned in the introductory part. And it would be nice to give links to topics where it is described so that the user can quickly find and read.
Do not insert the introductory part where it is not necessary.
Although the introductory part provides additional useful information, sometimes everything is clear from the heading itself. In such cases, you do not need to come up with an introductory text, if only it were.
For example:
Launch Mac applications through the Start menu.
Open the Windows Start menu and do one of the following:
- Click All Programs> Parallels Shared Applications and select the application you want.
- Enter the name of the application in the search field and select the desired application from the proposed options.
Do not make the prologue too long. The
prologue is too long annoying the user. In such cases, users often skip it and go straight to the list of specific steps.
If the introductory part is too large, you need to mention the main one and give a link to a separate conceptual page or reference page, in which everything will already be described in detail.
Sometimes, to visually facilitate reading of long text in the introductory part, bullets can be used. For example:
Do not tell in the introductory part how to complete the task. The
introductory part is not for this. What needs to be done, where and how - it is necessary to describe only later, after the introductory part.
However, in rare cases, you may need to tell users what they need to complete the task. In the example below, the introductory part tells users what they need to complete the task described in the topic.
Do not describe the results of the task in the introductory part.
This should be done in the final part ( Outro ).
The phrase before the instructions (Step Heading)
After the Intro, you must insert the "introductory" phrase (in English - "step heading"), which leads the user to the instructions: what exactly needs to be done to achieve a particular result.
For example, in Intro we write: “ If you have an installation disk and an activation key, you can use them to install Windows in a virtual machine. "
After Intro comes step heading: “ To install Windows: ”
And then the steps themselves:
1) Click here.
2) Choose this.
3) And so on ...
Note: if there is no Intro in the topic, then step heading is optional.
If the topic describes sequential steps, then step heading should look like “ To do something:” (“To do X:”).
For example: " To run the Windows:» ( "the To start the Windows:") or " To switch to full screen mode:» ( "the To switch statement to of Full Screen mode:").
Do not forget to put a colon at the end
If the heading uses user-friendly words, and you have to use complex technical terms or names of the interface elements in the instructions, you can do the following: in the introductory part you explain what the term means, and in step heading you already use it actively.
For example:
1) do poponyatnee header for the user:
"Run Windows in full screen» ( "the Set of Take Windows to the Up the Whole Screen")
2) The following Intro introduce the term "full-screen mode» ( "of Full Screen mode").
3) After this, you can use the term in step heading without fearing that it will not be understandable to the user:
“To enter full screen mode:” (“To enter Full Screen:”)
If the steps described in the topic are not a sequence of actions, but several ways to achieve the goal, then step heading should be done as follows: “Here are some ways to do something:” (“Here are ways to do X:”) or “ To do this, do one of the following: ” (“ To do X, do one of the following: ”).
For example, " Here are some ways on how to disable the Windows: » ( "Here are ways to shut down the Windows:") or " To connect the printer, do one of the following: » ( "the To the connect a printer, do one's of the the following: ”).
When creating step heading, you need to use those words that reflect the task described in the task topic. Here are some examples in English:
Page Title : Install Windows from an Installation Disc.
Task Covers : Installing Windows using an installation disc.
Step Heading : To install Windows.
Page Title : Adjust Coherence Settings.
Task Covers : Customizing how Windows appears and behaves in Coherence mode.
Step Heading: To customize Coherence mode.
Page Title : Set Windows to Take Up the Whole Screen
Task Covers : Entering full screen mode.
Step Heading : To enter Full Screen mode, do one of the following:
Numbered Steps
All topics that describe how to perform a particular task contain instructions on what to do. These actions in the text are usually either numbered (if it is a series of consecutive steps) or highlighted by bullets (if it is proposed to choose one of the list at your discretion).
Keep the list of necessary steps as short as possible.
Choose and describe the easiest and fastest way to perform an action. Alternative methods can be described in the final part (Outro) or in another task topic. Do not force the user to read the instructions in 4 steps, if all the same can be done by clicking on one button.
If the easiest way is to perform the action through the toolbar, describe this option. If the toolbar can be customized to your liking, and you have doubts, suddenly the user’s configuration of the toolbar differs from that described in the topic, describe everything as it is done with the default settings. As practice shows, most ordinary users rarely change the "factory" settings.
If you need to describe several ways how to perform an action in one topic :
If in many task topics of your book a certain action is repeated that can be performed in different ways (say, through a menu or toolbar), select one method and mention it sequentially in each task topic.
Если же есть простой и короткий альтернативный способ, и вы непременно хотите о нем рассказать, можно сделать это в том же шаге.
Например: «Чтобы открыть настройки виртуальной машины, нажмите Действия > Настройки или кликните иконку Настроить в правом верхнем углу» (“To open the virtual machine configuration, choose Actions > Configure or click the Configure icon in the top right corner.”).
Последовательно нумеруйте шаги, которые надо выполнить
Чтобы не раздувать описание и не выделять очень короткие инструкции в отдельные шаги (типа «Нажмите OK»), можно комбинировать 2 близких и связанных действия в один шаг, как показано ниже:
Используйте буллиты для выделения непоследовательных действий
Sometimes the user is offered several ways to choose how to achieve the goal. In such cases, the proposed options emit bullets.
For example:
If the names of graphic elements are in the list, highlight them in bold for clarity.
If the action that the user needs to do is list a number of graphical interface elements (menu items, daws, etc.), start each option from a new line, highlighting item name in bold. After the element marked in bold, put a colon and then explain the description in plain text.
As shown in this example:
If the text in the topic refers to various interface elements many times, it may be worth creating a separate help topic in which these elements will be described.
This will be especially useful if many topics in the guide refer to the same elements. In this case, at the beginning of the topic, you must give a link to the reference topic in which the mentioned element is explained.
If this element is mentioned again later in the text, you no longer need to give a link to it - just one at the beginning. When there are a lot of links in the topic, this can complicate the perception and understanding of what is written.
The final part (Outro)
Outro is the final information that comes after the numbered steps. Try to make the final part shorter - use no more than 3 paragraphs, each of which consists of a maximum of 3 sentences.
Use Outro to describe the results or consequences of these actions.
An example of a result or consequences can be:
• Information about where any files were installed;
• A message appears that will require additional actions from the user;
• Settings that the user will need to switch after the described actions have been completed.
For example, the final part of the topic on how to make Parallels Access work only on Wi-Fi, says the following: “ If you configured Parallels Access to work only on Wi-Fi and no wireless networks are currently detected, a message appears asking you - Would you like to connect via 3G? ".
In the final part of the topic, you can describe an alternative way to complete the task.
If the alternative method can be described in one sentence, you can do this in the final part of the topic.
Outro can provide more information that pertains to the current task.
Such information can inform users about what else they can do after completing the described task.
In the following example, the topic describes how to find a file from a virtual machine in macOS Finder. And in the final part of the topic describes what else the user can do with the file after the file is found.
In Outro, you can describe additional information that only some users will need.
For example, in the final part of the topic about integrating Windows virtual machines into macOS, you can write the following:“If you have a MacBook Pro 2016 or later, you can work with some Windows applications using the Touch Bar”
Break up long tasks into short steps
Basically, task topics are short and fit on one page. However, if some complex and very long task is described, which can be divided into stages, stages and procedures, it is worth logically separating the information and describing each stage in a separate topic so that the description looks simpler, better read and understood.
The following is an example from the contents of the Parallels Desktop User's Guide. The screenshot shows a chapter that describes various ways to install Windows in a virtual machine. And one of the ways - how to import data from a remote computer - is divided into several topics.
To be continued ...
(in the next part we will talk more about conceptual and reference topics and topics that help solve problems)