It’s one thing to produce a document, but it may be another thing to be sure it is accurate and helpful. Really good documentation doesn’t just check the box to show that you have something available, it assists people in doing their jobs. So how can you be sure that a user guide or a help system or any other kind of document is accurate? How can you be sure that it’s not out of date because of system updates that happened after you wrote it?
The Four-Eyes Principle
Many industries use a four-eyes principle to have a second person check work before it goes out. Stock traders have someone rekey an order before it goes to the market. If the two orders don’t match, the order isn’t sent out. Hospitals have a second person verify key information before surgery.
In tech writing, the best way to implement the principle is to have a second person not just proofread a document, but actually go through step-by-step, following the instructions in the guide to see if they are correct. The second person checks button names, procedure sequences, results of actions (what happens if you click that Submit button, for example, do you get a confirmation message telling you what happened?), screen and dialog box names, and so on. There is nothing more confusing to a reader than to see a reference to the “Data Analysis Screen” and find that they are looking at the “Product Data Screen.” What? Is this the same thing?
Readers lose confidence in a document when there are errors in simple things like labels, and they may abandon the guide entirely.
Who Should Check?
One good way to check a document is to give it to a novice user and then sit with the user as he or she tries to do the tasks outlined in the document. Resist the temptation to explain or help! Just make notes of every place the user hesitated or got confused.
In a large tech writing group, one writer can check another writer’s work, especially if they are unfamiliar with the product. But with most people working today on very lean staffs, that may not be possible. So instead, a user who will be doing the job and actually using the document can be the pilot user and give feedback.
Interns can also be used as reviewers, although bear in mind that they will not have the background in the work itself and so may either flag things that would actually be clear to someone who is more experienced or miss terminology that is actually wrong.
If all else fails, let the document “rest” overnight or longer and then read it again with a critical eye to accuracy.
What to Look For
Reviewers should note absolutely everything that seems confusing or wrong. The idea is to “break the document.”
Many errors in documents are things that were actually correct when the document was originally issued. (Kind of “I was for it before I was against it.” ) Changes in software that seem easy to developers play havoc with documentation. That’s why you check the document before you publish it. (A future post will deal with review cycles to keep pace with changes and keep documents from becoming obsolete.)