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

 * Don't write an essay.
 * Images and illustrations can explain better than words.
 * Put yourself in the reader's 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.
 * Don't use allusions. Your audience might not know to what you're referring.
 * Use short sentences 15 to 25 words on average.
 * One sentence per idea.
 * Break the text up, one concept per paragraph.
 * Use plenty of white space in between the sentences.
 * Use the active voice.
 * Do not use adverbs.
 * Do not use adjectives.
 * Avoid making nouns from verbs.
 * Use good grammar and punctuation. Use a spellchecker before saving.
 * Review what you've written, to catch any errors you may have made.
 * Try to balance comprehensive coverage with not 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. All steps should make sense to one another.
 * Make no assumptions that the user will know or understand something, unless this is a prerequisite for 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 where they apply.
 * 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