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.

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.

Examples

 * Heathkit manuals, Archive.org