Saturday, October 2, 2010

Consistency

Technical writing is not creative writing. Do not try to find different ways of saying the same thing in the same document. The goal in technical writing is to communicate everything the reader needs to know to perform a task with the least possible opportunity for the reader to misunderstand.

Consistency can seem boring, but if you use the simplest and most clear language possible, all readers should interpret the instructions correctly. Adding unnecessary adjectives, articles, adverbs, and other embellishments just gives the reader opportunities to confuse the matter.

Do not change the name of an item after it has been mentioned once. This should be a no brainer, but I've seen manufacturer manuals where there same part was called by two or even three different names. I've seen manuals where a part was called one thing in text and another in the illustration. The situation is worse when there are several manuals for a piece of equipment that were apparently written by different departments.

The answer to this problem when I was writing military manuals was having a staff of technical editors who ensured all documents were consistent in format and wording and compliant with military specifications. The problem in civilian companies I've found is that the technical publications staff usually consists of a couple writers at most and the editing consists of reviews performed by subject matter experts on the sections that concern them. Seldom does anyone look at the project as a whole. So, it is up to the writers to edit their own work, and no matter how closely they proof they will likely overlook some mistakes they made in the first place.

1 comment:

  1. Thanks for sharing the really nice information .
    Automationshift_ India’s 1st CXO conference on AI & Automation | WTC Bangalore.CXOs share their vision on how they are leveraging AI + automation + machine learning to drive higher efficiencies across organizations #Automation#changes#business#technology within their companies.
    twbShift

    ReplyDelete