SciTrans Logo Image  

Home

Email

Advantages

Articles

Research Links

Free Backgrounds

Free TekTracer Helpdesk

Contact Us

Link to TruthAndTallTales.com

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

©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."

Online writing lab

Grammar and style guide

Strunk and White summary

Cliché finder

Quotations