How to write technical documentation

Your reader will get your message clearly when you use Plain English techniques, those that focus on the audience and where you:

• use everyday English whenever possible
• use simple sentence structure—2 lines is long enough
• use headings and lists—direct the reader’s eye and lead them through the document
• use tables—a picture tells a 1000 words
• explain technical terms if necessary
• use the active voice—‘we did it’, not ‘it was done by us’
• use direct speech—‘we will’ not ‘the organization shall’
• use lots of white space—the body language of the document
• are concise
• are positive—‘when you send us the form we will…’ not ‘we cannot assist until you return the form’

Businesses writing steps

1. Tell me what you want me to know or do,
2. Tell me why and how,
3. Tell me what to do next.

This approach is quite different from what we were taught at school:

1. Introduction
2. Facts and figures
3. The conclusion or statement of what you want