Task-Oriented Writing for Techies
This chapter is from the book
This chapter is from the book
This chapter is from the book
Don't tell me how it works, tell me how to use it.
—A customer
Task-oriented writing is writing in terms of how the user does the task. You rarely help your users when you tell them only how a product works or how it is structured internally. Your users have a job to do, so they need practical information—how-to information.
You need to understand the tasks that you're writing about from your users' perspective. Do a task analysis to determine which tasks are most important to each group of users, which tasks are most frequent, and which tasks are most difficult. Make a list of the high-level tasks that users will do with your product.
You can divide high-level tasks, such as getting started with the product, into groups of lower-level tasks, such as installing the product and setting up the product. Each of these tasks might also be divided into still lower-level tasks until you have groups of manageable tasks that make sense to the user. For example, opening a bank account is a discrete task that makes sense for a user to do. However, the action of typing an address might be a step of a task, but it is not a task on its own.
Task topics, whether high-level or low-level, are the most important types of topics for users because tasks help users do their jobs. Users are frustrated if they cannot complete a task. Task-oriented topics get the user back "on task." Like a compass on a journey, tasks provide direction.
To make information task oriented, follow these guidelines:
-
Write for the intended audience.
-
Present information from the user's point of view.
-
Indicate a practical reason for information.
-
Focus on real tasks, not product functions.
-
Use headings that reveal the tasks.
-
Divide tasks into discrete subtasks.
-
Provide clear, step-by-step instructions.
Write for the intended audience
Before you start writing, be sure that you have a clear understanding of your audience. For example, if you are writing for managers, you might include only high-level tasks, such as evaluating and planning, or a high-level view of other tasks. Similarly, if you are writing for end users, avoid system administrator tasks.
Be sure that the information that you include in your topics is of interest to your audience. For example, your product might have a powerful new help system, but a description of the help system features is of little interest to the person who is installing the product.
The following passage shows a simple task that is explained in detail. However, the audience consists of users who want to use an advanced feature and therefore do not need help performing simple tasks. This information will frustrate all but the most patient advanced user.
Original
To customize your settings:
-
Go to the file tree.
-
Click the INFODIR folder.
-
Right-click the SETTINGS.DEF file and select Edit from the menu.
-
Change the settings that you want in the file.
-
Click File —> Save to save the file.
-
Click File —> Close to close the editor.
Revision
To customize your settings, edit the INFODIR/SETTINGS.DEF file.
In the revision, the task is handled much more simply. The revision quickly provides the users with the information that they need, because the writer understands the skill level of the audience.
For more information about how much detail to provide based on the type of user, see the completeness guideline "Cover each topic in just as much detail as users need" on page 79.