©2007 SciTrans
Ask the right questions and deliver good writing
Begin by asking questions like - What are the objectives of this documentation project? How can these objectives be met? What is the document's scope? What content must be included?
What do you want your readers to know, feel, ask, or do after reading? How will the project influence its readers? Will beliefs be changed, objections overcome, etc.?
How will readers use the documentation? The reader's role determines his requirements and the document's context. Possible contexts might include:
General overview |
Background information |
Design documentation |
Installation procedures |
Who is the documentation intended for?
- Experts — such as scientists and engineers
- Managers and executives
- Technicians
- End users — such as consumers, students, and employees
- General audiences — which may include stockholders and potential customers
Now that you've established who, determine their needs. What must they know and why?
Experts are interested in background, theory and applicability. Include research findings, summarize known and unknown elements of the topic. Provide evidence first. Present conclusions and recommendations last.
Busy managers need information on which to base decisions. Save them time by beginning with summaries, conclusions and recommendations. Emphasize cost and effectiveness. Keep the information quantitative and concise. Identify and evaluate alternatives. Supply recommendations and the logic on which these are based.
Technicians need installation, maintenance and repair information. Generally, they want to know "how" software or equipment works, rather than "why" it works. Provide them with concise information. Include schematics of program logic, parts diagrams and troubleshooting guides.
End users need to know how to use software and equipment easily and efficiently. Illustrated sequential information is appropriate. Verb driven, short sentences are effective. Get right to the point. Avoid distractions.
A general audience reads material it finds interesting — particularly material relating to daily life and practical matters. An informal, conversational approach works best. Emphasize "what" more than "why."