Help:Effective technical writing

This attempts to outline some basic principles for effective technical writing to communicate practical knowledge. Technical writing is describing complex subject or complicated procedure and breaking it down to make it understandable.

Key features

Clear communication

• Put yourself in the readers place, write appropriately for your intended audience.
• Use plain readily understood words.
• Use words with unambiguous meanings.
• Be concise, cut out redundant words.
• Use precise terminology.
• Avoid jargon.
• Avoid acronyms.
• Use short sentences 15 to 25 words on average.
• One sentence per idea.
• Break the text up, one concept per paragraph.
• Use plenty white space in between the sentences.
• Use the active voice.
• Do not use adverbs aka weasel and peacock words.
• Avoid making nouns from verbs.
• Try to balance comprehensive coverage without overwhelming with too much information.

Complete explanation

• Must be true, references are useful to validate the text.
• Put important information first.
• Be logical and sequential. Have no gaps in the logic and all steps should make sense to one another.
• Make no assumptions the user will know or understand something, unless this is a prerequisite from all users.

Highly organised

• Divide into sections and subsections.
• Start with a general outline and explain towards more specific details later on.
• Use ordered lists for your step-by-step procedure writing.
• Use parallel constructed lists.
• Use flow charts to illustrate decision making processes.
• Use images with descriptions and place them adjacent to the text.
• Use links to connect related topics and sections.

Further reading

• Letting Go of the Words: Web Content that Works by Ginny Redish, Morgan Kaufmann, 2007, ASIN B005NZ5K0W
• Every Page is Page One by Mark Baker, XML Press, 2013, ISBN 1937434281

External links

• 18F Content Guide
• Characteristics of Technical Writing

Examples

• Heathkit manuals, Archive.org