This chapter is from the book
This chapter is from the book
This chapter is from the book
Present information from the user's point of view
Writing from the user's point of view brings the user into the "story," so that users can easily imagine doing the task that you describe. Such writing has these characteristics:
-
It is predominantly directed at "you" (second person).
-
It uses the active voice, with verbs that denote actions that the user does as opposed to actions that the product does.
-
It gives a reason for the actions.
The following passage is written from a remote, impersonal point of view:
Original
The system should not be shut down during processing. If such a shutdown occurs, the system should be restarted with the START RECOVER command.
Revision
If you shut down the system during processing, you might lose data. Use the START RECOVER command to restart the system and recover any data from the log.
The original passage is passive and indefinite about who does the action and why. In the revision, the information is presented to make the user an active participant. The phrase "you might lose data" expresses the reason for the action in terms that users can relate to personally—they don't want to lose data.
The following passage leaves the users out of the story altogether:
Original
Subsequent installation of the HIGS feature allows InfoProduct to run unattended.
Revision
If you want to run InfoProduct unattended, you must install the HIGS feature. You can install the HIGS feature after you install InfoProduct.
Users don't know how the information in the original passage pertains to them. The revision adds the users to the story and explains what they need to do to use the feature.
When you provide task help, you have the advantage of knowing where the users are in the product interface and, therefore, what part of the task they need help with. This advantage allows you to write a help topic that's specific to the user's position.
For the following help topic, assume that a user accesses online help from the Primary Key page (which is the third and final page) of the Create Table wizard.
Original
)
The user has already completed most of the steps of the "Creating a table" task and needs only information about how to specify a primary key, which is a subtask of creating a table. The original help topic wastes the user's time because it provides steps that the user has already completed.
Revision
)
The revised help topic presents the task from the user's probable position. The revised topic also provides a link to a definition of a primary key for users who need to understand that concept before proceeding with the task.
When you understand the user's point of view, you can write task-oriented information that helps users do their tasks.