Skip to Content Skip to Main Navigation
 

7 Technical Writing Mistakes to Avoid in 2012 

21st December 2011 Posted in Blog, Communication, Documentation, Technical Writers 4 Comments

Image for 7 Technical Writing Mistakes to Avoid in 2012

We all make mistakes when we write, but when writing technical documentation, small mistakes can add up to a large consequence – and they could even harm the user or the person on the receiving end.  Since it’s about that time to make New Year’s resolutions, it’s a good time to remember common mistakes made in technical writing – and then promise not to make them next year. Here are seven mistakes to be watch for and avoid in the new year.

Technical Writers Should Not…

  1. Be vague – If your word choices are vague or you use passive voice, your reader may not understand what you mean.
  2. Avoid templates – When your organization has templates for previous technical documents, use them.  This will create congruent and useful documents. Users will get to know what to expect in your documentation.
  3. Ignore the reader – You always need to keep the reader in mind, who they are and for what purpose they’ll be using your document.
  4. Write without a plan – Start with a plan in place as to how you might approach the technical writing document, what it should accomplish and how it will look when finished.  This will save you time and energy as you begin writing.
  5. Use contractions – It is true.  You need to spell out your words instead of contracting them. Leave contractions for less formal, approachable writing, like blog posts. 
  6. Assume anything – Again, don’t assume your reader will understand what you mean until you tell them what they need to know.
  7. Edit their own work – Always have another set of eyes look at the document you create so you can be certain your word choices and phrases are effective for a larger audience (outside of yourself).

Everyone makes mistakes, but knowing how to the avoid the most common ones in technical writing is a good way to begin to improve your writing.

Related: 2011 Technical Writing Resolutions (Did You Ascribe to/Keep Any of These?)

What additional mistakes would you urge technical writers to avoid in the new year? Comments are appreciated. Have a happy holiday season from all of us at WAI!

Be Sociable, Share!

4 Comments

  1. By Julianon 8th, January 2012 at 8:47 am

    I would add change the first one to “Be negative” – Readers are more likely to respond to positive reinforcement than negative. If you can say something affirmative do so.

    And why replace the “Be vague” mistake? Because the explanation is too vague for me.

    Firstly vagueness and passive voice are not the same. For example, “On turning on the monitor the screen lights up from initially being black” is not at all vague, even though it is passive.

    Secondly, I have always taught my acolytes that mostly ambiguity is too be eschewed, but does have a place sometimes, when the reader is able to interpret the correct meaning, dependent on the specific reader at the time.

  2. By editoron 10th, January 2012 at 2:55 pm

    Julian:
    Thanks for your comment. Yes, I can see a place for being positive. As to trying to lump ‘vague’ and ‘passive’ in the same point? The post actually says vague OR passive, and (to me) doesn’t imply that both necessarily go hand in hand.

    While I can see a place for passive voice, I don’t agree that being deliberately ambiguous serves any purpose in documentation.

  3. By Cynthia Arbuckleon 12th, January 2012 at 3:31 pm

    I think these are all good things to avoid in technical communication. I do agree with another post that contractions can often soften the hard edge of more technical language, but we still adhere to the best practice and don’t use contractions in our documents.

    Another thing to avoid is using the adjective, “login,” as in “login screen” as a verb. If you’re logging in, make it two words, “log in.”

    Thanks!

  4. By editoron 12th, January 2012 at 4:10 pm

    Cynthia:
    Thanks for your comment. “Login” could also be used as a noun – “Use your login to access the information.” However, a good style guide should address this issue for consistency’s sake.

Leave a Reply