Helping User Complete the Task¶
We have our all resources and information in our bag. Now, what to do with this information?
Let us understand first that there can be two ways we can structure our information. Choosing any of these two can help the user complete the task. They are:
- Focus on Product
- Focus on Process
To achieve the difference in two, we have to conduct audience analysis. Audience analysis will narrow down the content and help us understand the requirement of the audience from the technical document.
Focus on Product¶
In this approach, the content is function-oriented. It systematically explains each function, feature, or interface element of a product. For example, The menu options under File:
- Open - Opens an existing file.
- New - Creates a file.
- Save As - Saves to a new file with a different name.
This type of information is providing conceptual knowledge to the user. It focuses on the properties and functions of the product. Such types of conceptual topics are generally covered if the audience includes admin and developers. The audience wants to know more about the specific function and its properties. They are very well aware of the product. This approach is full of technical jargon.
This type of approach does not help the end-user. And of course, not at all task-oriented. Instructions using this product approach are hard to make work. Sometimes the name of a button doesn’t match the task it is associated with; sometimes you have to use more than just one button to accomplish the task. Therefore, product-focused instructions always have prerequisites or prior knowledge of the product.
Focus on Process¶
This type of approach focuses on task orientation. End-Users want information about how to do real tasks, not a list of the buttons and fields on the product interface. By presenting the information from the perspective of tasks that users recognize and want to perform, make the information more relevant. For example, This topic explains how to work with a document. You can do the following tasks:
- Create a document
- Open an existing document
- Rename a document
This type of task-oriented approach helps the user understand the product well and what all things they can do with the product and addresses their purpose of reading a technical document.
Therefore, the process-focused approach is more relevant, practical, and utility-oriented.
Now, we are clear with the structure of the content that needed to be framed. Most of the time, TW prefers a process-oriented approach to help the user complete the task at hand.
The next question you will ask is how to achieve the process-oriented document.
To achieve this, we have to keep in mind a few elements that form the content. This element varies from grammatical structure, content description method, to the style adopted.
Grammar Structure¶
Use active voice¶
Active voice puts the agent or performer of an action at the beginning of a sentence. Active voice emphasizes who or what performs some action. Active voice needs less processing time to understand.
Use present tense¶
Using present tense helps keep the writing style active and direct. The present tense is easier to translate and more engaging. Use the past or future tense only when the present tense would be misleading or illogical.
Use imperative verbs¶
The imperative verb addresses the user and clearly identifies the action that the user should perform. Use the imperative mood for task information.
Content description method¶
User’s Perspective¶
When you understand the user’s point of view, you can write task-oriented information that helps users do their tasks. 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.
Headings¶
Use headings that reveal the tasks. Users should get an accurate idea about the content of the topic from the heading. Each heading should reveal that the topic contains information about a task, and what that task is.
Task Segregation¶
After you identify your main tasks, you need to divide them into discrete subtasks so that you can provide usable step-level information. Be sure to separate your tasks into discrete subtasks such that each subtask contains only one distinct task, yet contains sufficient content to stand alone.
Provide clear, step-by-step instructions.
Completeness¶
To ensure that you achieve completeness in your technical writing, it is important to examine both the text and the visual components of your document.
Textually complete documents provide the audience with the exact amount of information they need to complete a task or understand a topic.
Concreteness¶
Concrete elements define, illustrate, compare and contrast, and even enliven information. Therefore, use scenarios to illustrate tasks and to provide an overview. Make code examples easy to adapt by providing proper links or setting them apart from the content.
Relevance¶
When you explain the task-oriented information to the user, it becomes very important to tell them the relevance of the information you are providing to achieve the goal of completion of the task and understanding the method.
Visual elements¶
Use graphics¶
Use graphics that are meaningful and appropriate. Choose graphics that complement the text. Ensure that each illustration accurately depicts the object, concept, or function that it is designed to illustrate and that it does so as simply as possible. Use visual elements for emphasis. Use visual elements logically and consistently.
Use visual cues¶
Rather than burying text examples in a paragraph, set them off, perhaps by starting a new paragraph or a new line, adding a heading or label, using a list, or adding a column to a table.
Summary¶
To help user complete the task, remember these rules:
- Focus on the audience.
- Be clear and logical.
- Consider every word.
- Keep it brief.
- Be active and engaging.
References:
IBM’s Developing Quality Technical Information - A Handbook for Writers and Editors
Task Analysis and Task-Oriented Documentation - By David Murray