Some Technical Writing Tips

Technical writing has a certain mystique, which is unfortunate. Technical writing is writing about technical subjects, not writing to sound technical. This concept confuses many writers. Technical writing should be as uncomplicated as any other kind of writing.

Writers want readers to understand the information they share. Readers want to grasp that information. A writer’s goal is to ensure readers understand the information. Achieving that goal is possible. Here are a few suggestions toward accomplishing this goal, in no particular order.

  1. Identify and understand the target audience.
  2. Some topics may be shared assuming a certain level of expertise. When in doubt assume the reader knows nothing about the subject. Offer as much information as possible without insulting or degrading more knowledgeable readers.
  3. Focus on clarity.
  4. Keep thoughts separate. Write simply and logically.
  5. Use only one thought per sentence. Use only one sequence of thoughts per paragraph.
  6. Be precise, explicit. Avoid confusing the reader.
  7. Avoid the ambiguous word it.
  8. Be objective. Technical writing is about sharing information and not evangelizing.
  9. Be comfortable using an active voice and the present tense.
  10. Technical writing need not be dull because the subject is technical. Let the reader enjoy the material.
  11. Explain acronyms, abbreviations, and jargon.
  12. Avoid cluttering the page. White space is useful space — used to calm the reader’s eyes (and nerves).
  13. Write from the positive viewpoint, not the negative.
  14. Outlines and lists are useful — use them.
  15. Read out loud when stumped. Sometimes hearing the text helps clarify.
  16. Let proofreaders and editors do their jobs. The worst proofreader and editor is the author.
  17. Avoid wordiness. Impress readers by how well they understand the material, not by how much you know.
  18. Avoid pompous words.
  19. Rewrite, proofread. Rewrite, proofread. Rewrite, proofread.
  20. Writing is similar to other skills — practice, practice, practice!

Technical writing is the same as any other writing. The subject is technical, not the writing.

Remember the mission: to help people understand complex material.

Posted: Category: Usability Tagged: Tech Writing

Next: Y2K

Previous: Debian and Wireless