Writing Technical Documents

writing technical documents"writing technical documents"

Writing Computer Courseware - How to Write Good Technical Dcoumentation

It is a truth universally acknowledged that good training manuals don't have flowery introductory sentences like this one!

When writing technical documentation, we believe there are 4 important principles to stick to:

• Use the active tense wherever possible


• Keep paragraphs short


• Use diagrams where you possibly can


• Use simple words

These principles are discussed under separate headings below.

Use the Active Tense

The passive tense should be avoided if possible.  Sentences are better written in the active tense.  Paragraphs written in the active tense can be understood more easily.

Or to put it another way: avoid the passive tense if possible; write in the active tense and people will understand you more easily.

We hope that these examples prove the point!

Keep paragraphs short

If you want to show off your ability to write long sentences, with intricate nested subclauses and complicated punctuation; if you really hanker after a job writing prose for one of the more learned periodicals; if you can't stop putting semi-colons in your paragraphs, and listing more thoughts than one sentence can reasonably support; if all of these are character traits of yours, then maybe you shouldn't be writing technical documentation.

The last sentence was an example of the style you should be avoiding.  Use short sentences where possible, without being staccato. 

Use Diagrams Where Possible

We can't illustrate it in this article, but a diagram can speak a thousand words.  To take one small example, imagine trying to explain how the heart works without a diagram like the one at http://tinyurl.com/27wanx. 

Use Simple Words

It should be axiomatic that circumlocution and periphrastic English bewilder those not erudite enough to comprehend the meaning of an article.

Or to put it another way, use short words where possible.  Here is a quick guide:

• Never use encounter; use meet instead


• 
  Use things rather than employing them


• If you're choosing between two words, use the shorter one


• Use the words very or extremely sparingly, if at all

 As a guide, you should aim your article at 10-year-olds!

So there are 4 rules to follow when writing articles - for more help, the Economist style guide is an excellent resource (it's at http://www.economist.com/research/StyleGuide/index.cfm).

About the Author

Andy Brown is an author of computer training courseware for Wise Owl Business Solutions.  You can see examples of our Microsoft training courseware at http://www.wiseowl.co.uk/courseware/index.htm, and see what Wise Owl do at http://www.wiseowl.co.uk .

Translating and Localizing Documents - Cherryleaf Interview with Lloyd International (4)


writing technical documents
writing technical documents