Help:Effective technical writing

This attempts to outline some basic principles for effective technical writing. How to communicate practical knowledge about a complex subject and break it down into understandable chunks.

Key features

Collaborate

• Technical documents are hardly ever written alone.
• Ask the experts.

Clear communication

• Put yourself in the readers place, write appropriately for your intended audience.
• Use real world examples that your audience will understand.
• 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.
• Use a consistent familiar style.

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.
• First explain the simple aspects then go into more detail about the complex facets.
• Use ordered lists for your step-by-step procedure writing.
• Use parallel constructed lists.
• Use tables.
• 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.

Usability testing

• Test that the writing is understood as intended and rewrite until it is.

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