Problems in Materials Written by Non-writers

Many organizations involve the development engineers to prepare documentation for various reasons—because of limited resources, time constraints, or probably because they don’t understand the importance of documentation. Some of them feel that the engineers know the product/application better than anyone else, so it is better if they create the documents.

Example: The following are some of the prize-winning entries for the Worst Technical Writing Contest held by Metamor Documentation Solutions.

  • Warning label on the side of a cash register: ¬†Before disconnecting, disconnect the connecting connector.
  • The text found in a reference manual of a manufacturing software: To add a part, use Add a Part. Note that you cannot delete a part using Add a Part. To delete a part, use Delete a part.

The trouble with writing is that there are no hard and fast rules or any magic formulae that make it an easy step-by-step task. The truth is, inspite of referring to style guides and procedures to create manuals, you have to re-conceive the rules every time you write because every occasion has its own specific set of requirements and problems. In such situations, the SMEs cannot make a right decision.

Some of the problems in materials written by non-writers are as follows:

Not Communicating What is Required: Click here for details

Lack of Audience Analysis: Click here for details.

Poor Presentation: The most common errors the information presented by untrained technical writers are:

  • Long and complicated sentences, even if they are grammatically correct.
  • Use of lengthy, crammed, and dense paragraphs:
    • When the information should be in a bulleted or numbered list.
    • Where a labeled figure or illustration would have explained the information.
    • Where a table would have done more justice to the job.
    • Lack of white space.
    • Lack of consistency. It is an important factor as it helps to avoid confusion

Poor Organization

The document may be complete and accurate, but it is useless if the users cannot find what they need, when they need it. This happens because the information is not organized properly. The most common errors in organization of information are:

    • Steps are not organized in logical order.
    • Inability to identify between essential and optional information/content.
    • Information not organized in logical and sequential flow.
    • Inappropriate navigational aids, which do not help the users in nding the required topic easily.
    • Section headings not used to logically separate information.
    • Unclear and vague heading (not appropriate to the text it deals about).
    • Sections not describing an idea or concept.

It is extremely easy to recognize a poorly written and badly organized documentation. But, it is equally difficult to prevent it, unless it is done properly.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: