Technical writing tips

• Organize the content of your writing
  
• Share insight and experience; don't teach or preach
• Attempt conciseness: be brief but complete
  
• Attempt precision; say exactly what you mean
  
• Use directly relevant examples to support claims
  
• Paraphrase, quote, or reference, just don't plagiarize
  
• Avoid passive voice (ie. "This was done.")
  
• Avoid hackneyed superlatives and unconditional words like "always" and "never"
  
• Strive for consistency in voice, tense, number
  
• Reduce the use of pronouns
  
• Prevent reader boredom with:
• occasional introductory prepositions,
• varying tempo,
• synonyms from the thesaurus
  
• Control reader emphasis with punctuation and continuation rather than underline and italics when possible.
  
• Read and emulate popular short-subject periodicals.
  
• Use (but don't abuse) spelling check software
  
• Always introduce acronyms before use later in the work
  
• Beware of overly specific jargon

Technical Writing as Persuasion

Technical writing is, at its heart, persuasion. If you, as the writer, are not convinced that something of worth happened that needed reporting, then your intended audience will probably be unconvinced as well. What? You didn't think about who was in your audience before you started writing? The written communication is a product. Products need consumers, Think about the description of a customer-satisfying product: inexpensive, accurate, easy to use, no squeeks, rattles, or buzzes, works under a variety of conditions, self diagnostic, etc. For a good written product these should read: concise, precise, organized, consistent, complete, adequately referenced, etc.

Writing is the era of electronic media is emminently perfectable. Learn from your mistakes. You wouldn't expect to make a complicated product perfectly, or even adequately, the first time-would you? Continuous improvement can only result from measurement of quality followed by immediate corrective action. What is quality in writing? Quality is usually more conspicuous in its absence. Few people can write poorly enough to remove information from the brains of the reader. Instead the poor writer often succeeds in taking up a lot of the readers time without transmitting much information. Transmitted information per unit time is a metric (units?) for determining quality. Another is the "Fog Index" developed by Robert Gunning. The Fog Index of 11 or 12 is near-optimal. Higher or lower values are undesirable.