Bad advice: how to write technical documentation? Part two
Tips on writing competent technical documentation for users.
Part 2
Continuing the guidance of our technical writer Andrei Starovoytov, which will help to make your user documentation easier and more understandable.
The beginning of the article can be read here , and we described the process of documenting and localizing our products earlier in this article .
')
In this part, we will examine in detail the topics of which the user documentation consists mainly (especially the User's Guide) - namely, the task-topics , which tell you how to solve a specific task.
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”), and several related tasks. For example, the topic “Optimize Performance” may consist of the following sections: “Save disk space automatically” (“Automatically Conserve Disk Space”) and “Set up your MacBook for better performance or to save power” (“Optimize Your MacBook for Longer Battery Life or Higher Performance ”).
We must try to write task-topics on the principle: one topic - one task. True, there is an exception - if you have two opposite tasks, they should be described in one topic. For example, if you need to describe how to switch a virtual machine to full-screen mode and how to get out of it later, this should be done within one 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.
Task Topics
Task topics consist of:
Sometimes it happens that the task-topic does not contain all the above sections - for example, there is no need to insert Intro or Outro. Next, we will focus on each section of the topic.
Headline
We must try to make such headings so that the user immediately understands what will be written in the topic.
Make your headlines capacious, but at the same time not too long. Long headers may not be fully displayed in some browsers or Apple Help Viewer.
When writing a title, use the imperative (“Do this”)
For example, “ Set up a printer using Bonjour ” (“Set Up a Printer Using Bonjour”).
Do not use imperative in the names of topics that do not describe how to solve a problem.
In the title of the topic, use user-friendly words, do not concentrate on the interface elements.
The user does not want to understand the features, terms, interface elements, etc. - he needs to solve his specific task. Therefore, in the title of the topic, try to use the words that the user himself would use. For example, if you call the topic “ Prepare Mac to use Windows applications” (“Set Up Your Mac to Use Windows Applications”), it will be much clearer for the user than the topic “About Virtual Machines”.
Try to formulate the goal as the user would probably do. For example, instead of “ Start a Remote Session ” (“Start a Remote Session”) - better name the topic “ Start working with Windows remotely ” (“Start Controlling Windows Remotely”).
If you need to use technically complex terms or interface names, then it is better to do this not in the title, but in the introductory part of the topic.
If you write documentation in English, the words in the title must begin with a capital letter.
Correct : Set Up Your Mac to Use Windows Applications
Wrong : Set up your Mac to use Windows applications.
(we will discuss capitalization of the title in more detail in the next part of the manual).
Introduction (Intro)
In the introductory part that comes right after the headline, you should write what the user needs to know before he starts 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 section you can talk about “Coherence mode”, in order to prepare the user for will be further used in the topic.
Do not insert the introduction where it is not necessary.
Although the introductory part provides additional useful information, but sometimes everything is clear from the title itself. In such cases, do not need to come up with an introductory text, as long as it was.
For example:
Launch Mac Applications from the Start Menu
Open the Windows Start menu and do one of the following:
Do not make the prologue too long
Too long introductory part annoying 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 should mention the main one and give a link to a separate conceptual page or reference page, in which everything will be described in detail.
Sometimes, to visually facilitate the reading of long text in the introductory part, it is possible to use bullets. For example:
Do not tell in the introductory section how to complete the task.
The prologue is not for that. What should be done, where and how - should be described 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 that they need to perform the task described in the topic.
Do not describe the results of the problem in the introductory part.
This should be done in the final part ( Outro ).
Phrase before instructions (Step Heading)
After Intro, you need to insert an “introductory” phrase (in English - “step heading”), which brings the user to the instructions: what exactly needs to be done to achieve this or that result.
For example, in the Intro we write: “ If you have an installation disk and an activation key, you can use them to install Windows into a virtual machine. "
After intro comes step heading: " To install Windows: "
And then the steps themselves:
1) Click here.
2) Choose it.
3) And so on ...
Note: if there is no Intro in the topic, then step heading is not necessary to insert.
If the topic describes successive steps, then step heading should look like “ To do something:” (“To do X:”).
For example: “ To start Windows:” (“To start Windows:”) or “ To switch to full-screen mode:” (“To switch to Full Screen mode:”).
Do not forget to put a colon at the end.
If you use user-friendly words in the heading, and you have to use complex technical terms or interface element names in the instructions, you can do the following: in the introductory section, you explain what the term means, and you are actively using it in step heading.
For example:
1) we make the heading more understandable for the user:
“Run Windows in full screen” (“Set Windows to Take Up the Whole Screen”)
2) Next in Intro, we introduce the term “Full Screen mode”.
3) After that, in step heading, you can already use the term without fear that it will be incomprehensible 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 to turn off Windows: ” (“Here are ways to shut down Windows:”) or “ To connect a printer, do one of the following: ” (“To connect a printer, do one of the following: ").
When creating step heading, you need to use the 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 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 with bullits (if it is proposed to choose something from the list at its own discretion).
Make the list of steps as short as possible.
Select 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 you can do the same thing by pressing one button.
If the easiest way is to perform an action through the toolbar, describe this option. If the toolbar can be customized to your liking, and you have doubts, all of a sudden the user has a toolbar configuration different from the one described in the topic, describe everything as 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 of the task-topics of your book, an action is repeated that can be performed in different ways (say, through the menu or toolbar), choose one method and mention it consistently in each task-topic.
If there is a simple and short alternative way, and you certainly want to talk about it, you can do it in the same step.
For example: “ To open the virtual machine settings, click Actions> Settings or click the Configure icon in the upper right corner ” (“To open the virtual machine configuration, choose Actions> Configure or click on it).
Number the steps you need to follow.
In order not to inflate the description and not to single out very short instructions in separate steps (such as “Click OK”), you can combine 2 close and related actions in one step, as shown below:
Use bullets to highlight inconsistent actions.
Sometimes the user is offered several ways to choose how to get things done. In such cases, the proposed options emit bullitt.
For example:
If the list contains the names of graphic elements, make them bold for clarity
If the action to be performed by the user lists a number of GUI elements (menu items, checkboxes, etc.), start each option with a new line, highlighting the item name in bold. After the bold element, put a colon and then plain text explaining the description.
As shown in this example:
If the text in the topic many times refers to different elements of the interface, it may be worth creating a separate reference 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 will be mentioned again in the text, it is no longer necessary to give a link to it - just one at the beginning. When there are a lot of links in the topic, it can make it difficult to understand and understand what is written.
The final part (Outro)
Outro is the final information that comes after the numbered steps. The final part should try to do shorter - use no more than 3 sections, 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 performed.
For example, the final part of the topic on how to make Parallels Access work only over Wi-Fi says the following: “ If you have configured Parallels Access to work only over Wi-Fi and no wireless networks are currently detected, a message will appear that asks you - would you like to connect via 3G? ".
In the final part of the topic, you can describe an alternative way to perform the task.
If an alternative method can be described in one sentence, it can be done in the final part of the topic.
In Outro, you can give more information that relates to the current task.
Such information can inform users about what else they can do after completing the described task.
In the following example, a topic describes how to find any 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 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 release or later, then you can work with some Windows applications using the Touch Bar”
Break long tasks into short steps.
In general, task topics are short and fit on one page. However, if a 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.
Below 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 into 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
Continuing the guidance of our technical writer Andrei Starovoytov, which will help to make your user documentation easier and more understandable.
The beginning of the article can be read here , and we described the process of documenting and localizing our products earlier in this article .
')
In this part, we will examine in detail the topics of which the user documentation consists mainly (especially the User's Guide) - namely, the task-topics , which tell you how to solve a specific task.
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”), and several related tasks. For example, the topic “Optimize Performance” may consist of the following sections: “Save disk space automatically” (“Automatically Conserve Disk Space”) and “Set up your MacBook for better performance or to save power” (“Optimize Your MacBook for Longer Battery Life or Higher Performance ”).
We must try to write task-topics on the principle: one topic - one task. True, there is an exception - if you have two opposite tasks, they should be described in one topic. For example, if you need to describe how to switch a virtual machine to full-screen mode and how to get out of it later, this should be done within one 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.
Task Topics
Task topics consist of:
- Header
- Prologue (in English “intro”)
- Phrases that lead to a description of what exactly the user should do (in English “step heading”)
- Numbered or numbered steps (in English “numbered or bulleted steps”)
- The final part (in English “outro”)
Sometimes it happens that the task-topic does not contain all the above sections - for example, there is no need to insert Intro or Outro. Next, we will focus on each section of the topic.
Headline
We must try to make such headings so that the user immediately understands what will be written in the topic.
Make your headlines capacious, but at the same time not too long. Long headers may not be fully displayed in some browsers or Apple Help Viewer.
When writing a title, use the imperative (“Do this”)
For example, “ Set up a printer using Bonjour ” (“Set Up a Printer Using Bonjour”).
Do not use imperative in the names of topics that do not describe how to solve a problem.
In the title of the topic, use user-friendly words, do not concentrate on the interface elements.
The user does not want to understand the features, terms, interface elements, etc. - he needs to solve his specific task. Therefore, in the title of the topic, try to use the words that the user himself would use. For example, if you call the topic “ Prepare Mac to use Windows applications” (“Set Up Your Mac to Use Windows Applications”), it will be much clearer for the user than the topic “About Virtual Machines”.
Try to formulate the goal as the user would probably do. For example, instead of “ Start a Remote Session ” (“Start a Remote Session”) - better name the topic “ Start working with Windows remotely ” (“Start Controlling Windows Remotely”).
If you need to use technically complex terms or interface names, then it is better to do this not in the title, but in the introductory part of the topic.
If you write documentation in English, the words in the title must begin with a capital letter.
Correct : Set Up Your Mac to Use Windows Applications
Wrong : Set up your Mac to use Windows applications.
(we will discuss capitalization of the title in more detail in the next part of the manual).
Introduction (Intro)
In the introductory part that comes right after the headline, you should write what the user needs to know before he starts 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 of an introductory part that describes why you may need to download and use ready 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 for any possible damage to hardware, software, or data loss that may occur while the user performs an action.
- Important information about potential problems or difficulties that, while not causing damage to your health, equipment or data loss, can occur during the execution of a task.
- Explanation: what a particular term means or how a feature works.
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 section you can talk about “Coherence mode”, in order to prepare the user for will be further used in the topic.
- Information about additional conditions : for example, in a topic that describes how to connect a printer through Bonjour, the introduction may inform you which versions of Windows support Bonjour.
- The conditions necessary to perform the current task : if the user needs to do or check something else before starting the task described in the topic, then this should be mentioned in the introductory section. And it would be good to give links to topics, where it is described, so that the user can quickly find and read.
Do not insert the introduction where it is not necessary.
Although the introductory part provides additional useful information, but sometimes everything is clear from the title itself. In such cases, do not need to come up with an introductory text, as long as it was.
For example:
Launch Mac Applications from the Start Menu
Open the Windows Start menu and do one of the following:
- Click All Programs> Parallels Shared Applications and select the desired application.
- Enter the name of the application in the search field and select the desired application from the options.
Do not make the prologue too long
Too long introductory part annoying 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 should mention the main one and give a link to a separate conceptual page or reference page, in which everything will be described in detail.
Sometimes, to visually facilitate the reading of long text in the introductory part, it is possible to use bullets. For example:
Do not tell in the introductory section how to complete the task.
The prologue is not for that. What should be done, where and how - should be described 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 that they need to perform the task described in the topic.
Do not describe the results of the problem in the introductory part.
This should be done in the final part ( Outro ).
Phrase before instructions (Step Heading)
After Intro, you need to insert an “introductory” phrase (in English - “step heading”), which brings the user to the instructions: what exactly needs to be done to achieve this or that result.
For example, in the Intro we write: “ If you have an installation disk and an activation key, you can use them to install Windows into a virtual machine. "
After intro comes step heading: " To install Windows: "
And then the steps themselves:
1) Click here.
2) Choose it.
3) And so on ...
Note: if there is no Intro in the topic, then step heading is not necessary to insert.
If the topic describes successive steps, then step heading should look like “ To do something:” (“To do X:”).
For example: “ To start Windows:” (“To start Windows:”) or “ To switch to full-screen mode:” (“To switch to Full Screen mode:”).
Do not forget to put a colon at the end.
If you use user-friendly words in the heading, and you have to use complex technical terms or interface element names in the instructions, you can do the following: in the introductory section, you explain what the term means, and you are actively using it in step heading.
For example:
1) we make the heading more understandable for the user:
“Run Windows in full screen” (“Set Windows to Take Up the Whole Screen”)
2) Next in Intro, we introduce the term “Full Screen mode”.
3) After that, in step heading, you can already use the term without fear that it will be incomprehensible 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 to turn off Windows: ” (“Here are ways to shut down Windows:”) or “ To connect a printer, do one of the following: ” (“To connect a printer, do one of the following: ").
When creating step heading, you need to use the 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 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 with bullits (if it is proposed to choose something from the list at its own discretion).
Make the list of steps as short as possible.
Select 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 you can do the same thing by pressing one button.
If the easiest way is to perform an action through the toolbar, describe this option. If the toolbar can be customized to your liking, and you have doubts, all of a sudden the user has a toolbar configuration different from the one described in the topic, describe everything as 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 of the task-topics of your book, an action is repeated that can be performed in different ways (say, through the menu or toolbar), choose one method and mention it consistently in each task-topic.
If there is a simple and short alternative way, and you certainly want to talk about it, you can do it in the same step.
For example: “ To open the virtual machine settings, click Actions> Settings or click the Configure icon in the upper right corner ” (“To open the virtual machine configuration, choose Actions> Configure or click on it).
Number the steps you need to follow.
In order not to inflate the description and not to single out very short instructions in separate steps (such as “Click OK”), you can combine 2 close and related actions in one step, as shown below:
Use bullets to highlight inconsistent actions.
Sometimes the user is offered several ways to choose how to get things done. In such cases, the proposed options emit bullitt.
For example:
If the list contains the names of graphic elements, make them bold for clarity
If the action to be performed by the user lists a number of GUI elements (menu items, checkboxes, etc.), start each option with a new line, highlighting the item name in bold. After the bold element, put a colon and then plain text explaining the description.
As shown in this example:
If the text in the topic many times refers to different elements of the interface, it may be worth creating a separate reference 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 will be mentioned again in the text, it is no longer necessary to give a link to it - just one at the beginning. When there are a lot of links in the topic, it can make it difficult to understand and understand what is written.
The final part (Outro)
Outro is the final information that comes after the numbered steps. The final part should try to do shorter - use no more than 3 sections, 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 performed.
For example, the final part of the topic on how to make Parallels Access work only over Wi-Fi says the following: “ If you have configured Parallels Access to work only over Wi-Fi and no wireless networks are currently detected, a message will appear that asks you - would you like to connect via 3G? ".
In the final part of the topic, you can describe an alternative way to perform the task.
If an alternative method can be described in one sentence, it can be done in the final part of the topic.
In Outro, you can give more information that relates to the current task.
Such information can inform users about what else they can do after completing the described task.
In the following example, a topic describes how to find any 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 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 release or later, then you can work with some Windows applications using the Touch Bar”
Break long tasks into short steps.
In general, task topics are short and fit on one page. However, if a 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.
Below 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 into 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)
Source: https://habr.com/ru/post/442224/
All Articles