This chapter is from the book
This chapter is from the book
This chapter is from the book
Indicate a practical reason for information
Giving users the information that they need is only part of task-oriented writing. Users need a practical reason for the information. They need to understand why you are giving it to them—how it is relevant to their task. The goal that the information serves must be apparent. A task is not just an activity, but an activity that is directed to a particular end.
To ensure that the information that you provide is relevant to the task, follow these guidelines:
-
Relate details to a task where appropriate.
-
Provide only a necessary amount of conceptual information in task topics.
Relate details to a task where appropriate
In a task topic, users should never wonder, "But why are you telling me this?" For example, to state that the records in a file have a certain size might leave users wondering, "So what?" However, if you tell them that they must build a library to hold the file and that the record size affects the way that they do this, they can understand why you are telling them about record size.
In a task topic, facts can puzzle users if you don't indicate what significance the facts have, as shown in the following passage:
Original
If the NORES option is used, the routines are link-edited as part of the load module. If the RES option is used, the routines are loaded separately.
Revision
Use the NORES option when you have sufficient space for routines to be link-edited as part of your load module. Use the RES option to save space by loading the routines only when you need them.
The original passage explains what the options do, but it does not relate that information to the user's task of deciding which option to use. In the revision, the facts are restated so that the user understands when to use which option.
At first glance, the following sentence appears to be only descriptive and to have no practical application:
Original
The BW_Message mapping table in the Data_LM directory can contain warning messages that are issued by InfoProduct when you create a request.
Revision
After you create a request, check the BW_Message mapping table to see if InfoProduct issued any warning messages. The BW_Message mapping table is in the Data_LM directory.
Users might glance at the original sentence and move on because it doesn't seem relevant. The revised sentence relates the information to the task of creating a request, so that users understand why the information is significant.
Provide only a necessary amount of conceptual information in task topics
Task topics should focus on providing only the information that supports the task. Task topics can contain:
-
Rationale for doing the task
-
Requirements for doing the task (such as prerequisite tasks or software)
-
Steps of the task
-
Tips and examples to support the steps
-
Information about follow-on (postrequisite) tasks
Do not mix significant amounts of conceptual information with task information. Users want to learn to do things without needing to learn all the concepts that are associated with a product. In task topics, provide steps as early as possible, and explain minor concepts briefly, if at all.
Separate the explanations of major concepts from the task topic by creating a topic for each major concept. Provide links to those concept topics from your task topic. That way, users who already understand the concepts can do the task, and users who need to learn about the concepts can go to the concept topics.
This guideline deals with overcompleteness and is similar to the completeness guideline "Include only necessary information" on page 84.
The following topic explains the concepts of a project and a suite before presenting the task:
Original
Creating test cases
Projects are collections of files that are related to a test case. When you create a test case, you must also create a project. You can, however, create a project before you create a test case. Each project can contain multiple test case files but only one main test case. You create projects in suites. Each suite can contain multiple projects. If you create one suite for each function that you test, the projects in a suite can contain the test cases that you create to test the function.
To create a suite:
-
Right-click a suite object and select New from the menu.
-
Specify details in the New Suite window.
To create a project:
-
Right-click a suite object and select New Project from the menu.
-
Specify details in the New Project window.
To create a test case:
-
Right-click a project and select New Test Case from the menu.
-
Specify details in the New Test Case window.
-
Click Record and work with the product that you want to test.
-
Click Save after you finish recording your actions.
The original topic starts with conceptual information and then tells the user how to create the needed elements. Users need to read through a big paragraph of information before they can start the task.
Revision
Creating test cases
You can create one or more test cases for each function that you want to test.
Before you begin:
-
Create a suite for the function that you are testing.
-
Create a project within the suite to hold the test cases and files.
To create a test case:
-
Right-click a project and select New Test Case from the menu.
-
Specify details in the New Test Case window.
-
Click Record and work with the product that you want to test.
-
Click Save after you finish recording your actions.
Related topics
Creating suites
Creating projects
Suites
Projects
Test cases
The revised topic does not explain all of the relationships of the elements. These elements are explained in detail in concept topics. Links are provided from the bottom of the task topic to these concept topics. In addition, the revised topic uses a prerequisite section that is labeled "Before you begin" to show that two of the elements must be created before you begin this task.
This separation of task topics and concept topics allows the writer to share the same concept topics across multiple tasks. For example, the task topic for creating a project can also provide a link to the "Projects" concept topic.
The revised task does not provide the substeps of the prerequisite tasks. Those steps are provided in separate tasks that are linked to from this task. Each of the three tasks is handled in a separate topic as explained in the guideline "Divide tasks into discrete subtasks" on page 33 of this chapter.