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

  • 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.

[1][2][3][4]

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