(Don't) Use the Magic Word

In order to write good technical content, you have to get past your everyday speak.  So often we see in existing documentation everyday pleasantries, as if the writer is writing a letter rather than formulating what often is extremely important detail.  You see examples of the writer saying please when trying to bring attention to an important point, and a user manual I edited recently even started off, welcome to ….; which is the sort of thing you might have at the front of your marketing material, but totally out of place in a technical manual.

Technical writing is about creating crisp, concise content for a target audience.  It does not set out to be entertaining.  Just think of the engineer pulling out the procedure for managing a potential failure or disaster, and the procedure has a welcome message, and says things like please and you may wish to….  It could be very annoying to maintenance and rectification personnel to have to wade through pleasantries or any other non-essential words when they have a job to do.  The point is that when you read a novel, you are relaxed and not time-constrained, so the author can entertain you with their fine rhetoric.  But even if you are simply reading a manual, you want the detail to go inside your head as quickly as possible. 

What makes me laugh at times and even sigh when I see it too often, is the use of words like wish and desire.  I see these words all the time in technical documents and there is no place for wishy-washy words in the technical writing world.  We are trying to write with no ambiguity at all and we must ensure that the words we use have no other connotations. 

Where this becomes totally essential is if you are getting your content translated.  Imagine how wish would end up through the translator software. If you wish to include the station name….. could come out as: If you appeal to the mother of all heavenly gifts for the inclusion of the station name…. in some off-the-beaten track language.  If you desire to include the station name…” could come out like: If you have the burning in your loins to include the station name….

There are many real and sometimes hilarious examples of  translation mayhem, but using words that can only be interpreted one way will ensure a much smoother translation.  Even if you are not sending your content overseas, consistency is essential.  If the word want does the trick, why then use wish or desire.  I have seen all three words in the same document, and one manual I looked at recently had five different ways of saying the so-and so screen is then displayed, and in one of those ways, the writer had the screen or form jumping out.  There seems to be a tendency for untrained writers to think they have to vary the language to avoid boredom.  But we are not in the business of entertaining, and people do not turn to manuals for entertainment. 

Nick