Writing Computer Courseware - How to Write Good Technical Dcoumentation

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 are4 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).

POST COMMENT

Causes of Memory Loss How to convert/rip DVD to T-Mobile myTouch 4G format? How to select a color laser printer in a changing economy Recover Hard Disk Failure - Urgent Report ! Slow Usb Hard Drive - Be Careful ! Improving Hard Disk Performance - Get Help Now ! Save Hard Disk Space - Easy Task ! Clean Harddisk - Tip! HP Ink Cartridges for improved Printing presentation Vibrams Fivefingers - Which Model Should You Buy? Flexo water-based ink used in several considerations - water-based inks, flexo - Printing Industry Why HP Laser Toner Cartridges Are So Popular SDXC Card – Understanding Your SDXC Memory Device