-
Notifications
You must be signed in to change notification settings - Fork 47
How to write task topics
The following guidance applies specifically to task topics for the Open Liberty docs. For general guidance on writing task topics, see Developing Quality Technical Information, Ch. 3 Task Orientation.
The topic title and orientation should emphasize the goal a user wants to achieve, not the tools or functions necessary to achieve the goal. For example: Connecting to a remote datasource rather than Using the JDBC feature.
Whether it's the majority of users overall or at the majority of users of a particular technology, focus on the 80% rather than the 20%. Don't document alternatives or edge cases.
Demonstrate that you understand the target audience's context and pain points. Address the user with documentation that talks directly to them. Use active voice.
Instead, provide a link to the 3rd party documentation. Make sure to link as directly as possible to the section or topic of the documentation that is relevant to your task topic.
Use numbered steps only if the information in your topic consists of tasks that must be completed in a particular order, with each step being a direct result of the previous step. If the information in your topic consists of a series of related examples that don't follow directly one from the other, use a bulleted list or subsections with descriptive headings instead of numbered steps. Numbered step-by-step instructions are not that relevant to a lot of the info we need to provide.
Subheadings should identify the low level tasks a user must complete in order to achieve their goal. The user should be able to take in the overall procedure and the tasks that comprise it at a glance, so that as they work through the topic, they'll have an idea of how smaller tasks fit in with the overall goal. Instead of generic template-style headings (Prerequisities, Procedure, Results), write contextual headings that reflect the smaller tasks that make up the high-level task.
In some cases, generic headings such as Before you begin and What to do next are helpful, but not all tasks need these sections.
This heading can identify tasks associated with other components or third party software that is documented elsewhere. However, the content should focus on things that the user who is completing the task would do, not things that someone else at their org would have done for them. Present greater infrastructure and configuration contexts as assumptions (For this task, we assume you have cluster logging configured...) rather than something you would expect the user to do themselves before they begin.
This heading should be reserved for follow-on tasks that are a logical next step to the task being documented, and for which there is documentation that you can direct the user to.
At the end of each sub-task and the conclusion of the topic, provide a concise statement of the results a user has achieved and how these relate to the overall goal the topic is documenting. Providing this feedback helps orient the user so they understand where they are in a task, what's left to do, and what they will achieve.