The challenge of producing great documentation is two-fold: collecting relevant information, and presenting it in a useful way to readers.
Getting Information
Writers often find that extracting information from technical staff is like pulling teeth. There are two reasons for this. One is that by the time documentation starts, the engineers are frantically working out the bugs, and trying to meet the deadline. Secondly, most engineers find documentation a boring distraction.
I take a different approach.
Using my unfair advantage (engineering background), I gather a great deal of information with little or no assistance from the design department. This is a welcome relief for the engineering department, and eliminates a lot of hassle. I approach the engineers with a list of smart technical questions. The first draft of the documentation is generally comprehensive, and has a high degree of factual accuracy.
With relatively little input from the engineering department, I can produce a lot of documentation.
Presenting Information
I bridge the gap between a well-informed technical staff with one context, and a savvy technical audience with a different context.
What will users/readers be thinking as they start working with the product? What questions will come up for them?
As they use the equipment more and more, what will they need to know to make better use of it?
If they can’t get the equipment to work as expected, the chances are it is because they are missing some crucial piece of information. What might that be, and how best to communicate it in a way that makes sense in context?
Context
Context colours how information is perceived.
Some users/readers may be experienced in the field, and with your previous products. Or they may be novices in the field, and new to your equipment.
The context of how the equipment is used can differ from what the designers expect. Certainly the context of a designer is different from the context of a user. I consider this as I write the documentation.
Frequently, the engineers are so immersed in the details of the equipment design, they miss two important things. First, the designers know far more about how the equipment works than the users ever will. What the designers may consider trivial and obvious, may elude the users for one reason or another. Secondly, the designers frequently operate in a vacuum. The users have a different reality, and may well be using the equipment in somewhat different way from what the designers assumed.
Assumptions
Assumptions are important. It is my job to take the information provided by the designers, together with what I learn from using the equipment myself, then work out what the users might need to know. I must also work out the best order in which to present that information. I need to filter the assumptions of the designers, and present the obvious to those who won’t find certain facts as obvious at all.
Translating English into English
In the end, it is a translation and filtering job. Creating great documentation means taking available information from a variety of sources (engineering department, marketing department, my own use of the product), and translating it into a comprehensive and digestible document catering to a variety of users/readers.
Do you want to find out more? Contact Doug Samuel