Help:Effective technical writing

Jump to navigation Jump to search

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.[1]

Key features

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.[2]
  • Do not use adjectives.[2][3]
  • 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.

[1][4][5][6]

References

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

Examples