Latest posts by techwriter (see all)
- 15 Questions to Ask After You Finish a Technical Document Project - February 12, 2018
- THY’s Perfect Information Design - February 9, 2018
- Waterfall vs. Agile Models in Technical Documentation - February 7, 2018
© 2010 Ugur Akinci
Usually the first chapter of a technical document is titled “Introduction” where the technical communicator provides a bird’s eye view of the rest of the document.
In that chapter, the “performance goal” of the document is spelled out clearly, as well as the “audience” it is intended for.
You can make that introductory chapter really useful by also specifying the CONDITIONS of the goal and the way to MEASURE whether it was performed successfully or not.
That way the readers can also decide for themselves whether they had been successful in following your document or not. After all, what good is a technical document if the readers cannot perform a task or procedure as described in the text, and do so within the specified conditions?
Another outcome of this exercise would be receiving meaningful reader feedback so that you may want to revise and improve your document in a future edition. Perhaps the performance goal is meaningful but the conditions and/or measurement criterion is/are unrealistic? You won’t know that unless you specify such conditions upfront in the introductory chapter.
Here is a typical “Performance Goal” statement from a typical User’s Guide:
“The goal of this User’s Guide is to explain the way XYZ-123 system works.”
This is a very poor performance goal statement on multiple levels.
First off, your job is to explain how the USER can PERFORM a TASK by USING this SYSTEM; not how the “system” works on its own. You’re not writing the guide for the system (!) but for the end user. Never forget that.
Secondly, the statement needs to mention not only a concrete TASK but also hint at the USER BENEFIT such a task would generate when performed successfully.
So, an improved version of the same statement might read:
“This User’s Guide describes how to use the XYZ-123 system to audit medical insurance claims and separate the fraudulent claims from the legitimate ones.”
Yet even this version does not describe how the user should measure success; and by that we mean the success of the documentation, not the system itself (which is another issue all together).
So here is another version:
“This User’s Guide describes how an operator can install, configure and start using the XYZ-123 system within 6 hours to audit medical insurance claims and separate the fraudulent claims from the legitimate ones.”
This is more like it. Now not only a specific task is describing with a hint of benefits, but a specific performance measurement criterion (6 hours) is also provided.
This introductory section can be rounded out nicely by including a “Prerequisites” list that most technical documents have. This is a list of hardware, software and all the other features and components necessary for the system to work properly. For example if you need to have Windows 7 operating system for the system to work, you need to include it in this list.
By thinking carefully about the Performance Goal statement you can help the users/operators understand what is expected of them and how they can measure their own level of success. And if you’re lucky, they’ll give you valuable feedback on the basis of that which will help you to improve your document in the future.