The majority of the documentation projects start out with a comprehensive inventory of the “features” a product consists of—the menus, icons, and dialog boxes of software. Although it’s certainly true that each of these items will eventually need to be documented, the problem with this approach is that it focuses more on the product than on the reader. As a result, the reader’s needs are subordinate to the idiosyncrasies of the product, resulting in the documentation that works only for people who already knows how everything works and is interested only in finding out a few details. A feature-based approach is apt for reference manuals, where the objective is to provide information on something the reader already knows. But it works poorly in user manuals, where the goal is to teach the reader how to do something. The users who want to learn how to do something requires considerably more context than a feature the list provides. A layperson needs a broad overview of what they can accomplish with the product, the main components that permit them to accomplish these goals, and how all the components fit together. More experienced readers already know something of this overall context, and instead, need more intermediate-level information, as well as a comprehensive view of the goals they can accomplish with the product. Lastly, all readers need to know the specific tasks that must be performed in order to reach each goal. Below this comes the finest level of detail: the steps required to complete each individual task.
Here are the some of the rules that must be followed while writing:
- Provide Broad-scale Context – Although the most documentation does an adequate job of describing the software features, the broad overview that shows how they fit together is often lacking. The documentation focuses too narrowly on tasks and procedures and, in so doing, fails to provide the larger goals that would help readers understand why they should perform the tasks and how each task fits within a broader understanding.
- Provide Intermediate Context – Having defined the broader structure of the document, the next step is to define the intermediate level of context for each of these groups: the tasks that, taken together, allow the user to accomplish a larger goal.
- Provide Low-level Context – At the lowest level of our hierarchy of context, provide information that guides readers in their use of tools and procedures. In other words, helping readers not just in using the product’s tools, but helping them use these tools effectively. The trick is to choose an appropriate level of detail. The approach discussed thus far ensures that your documentation meets the primary goal of any documentation project: providing enough understanding of a product that users possess the necessary intellectual tools to plan an overall approach to using the product and can determine all the tasks necessary to attain each of their goals. But,
ironically, the problem with this approach is that by focusing so strongly on the reader, it may neglect the product itself. As a result, certain key features of the product may be missed. This poses an obvious problem when the user encounters a feature, asks how to use it, and is unable to find any information on how to do so. The solution is straightforward: prepare a comprehensive list of product features and match it to the broad-scale, intermediate, and low-level contexts that you’ve prepared to ensure through your consideration of context that you have covered each feature. You’ll undoubtedly find some aspects of the product that you missed by focusing on the reader, and some of these may become new topics at one or more of the three levels
- Don’t Forget the Procedures – To prevent readers from being overwhelmed by a sea of text that conceals the procedural information, clearly, separate the context from
the procedures. In an online document, this might be accomplished by means of
hyperlinks. A short introduction beneath the main heading, perhaps as short as a single sentence and certainly no more than two or three sentences, provide, the necessary context for how to use this part of the documentation.
Visit ThomasEcafe.com, or call +65-82086393, or email info@ThomasEcafe.com to discuss.