Monday, October 26, 2015

Effective Writing

Having worked in corporate environment most of my life, I have seen many poor documents.  Organizations tend to expect their technical team to write the technical documents, and this does not always pay off.  Simply for this reason that having the knowledge of something does not mean you can also explain it well-enough for the layman to read and understand. 

Technical people most of the time – knowing the subject inside out – will leave the details out, because they feel everyone else would already know them and there is no need to rehash.  To me, a well-documented process, procedure or description is one that anyone off the street can read and fully understand.

Manuals that do not explain the step-by-steps in a proper manner and are not easy to follow,   are only good as a collector’s item or paper-weight.  Here I would like to offer a few hints in creating useful documents:

1.       Try not to end your sentences with adverbs; and instead use them mid-sentence.
2.      Using too many adjectives, may sound too biased.
3.      Use passive voice only when absolutely necessary.
4.      When using acronyms for the first time in the document, fully write it out and for any consecutive times that the acronym is used, have a reference glossary.
5.      Use words in their full form.  For example say, “Was not” instead of “Wasn’t”, or “Could not” instead of “Couldn’t”. 
6.      Try and make your sentences as short as you can. One description per sentence; and preferably one description per paragraph.
7.      Use simple words that are easily understood by anyone and do not require a dictionary.
8.      Especially in technical writing, try not to use pronouns like “I”.  Make your sentences in third person.
9.      Make your documentation look consistent where comma, colon, and semicolon are concerned.
10.   Have a template to follow, to make it easier for the reader to know what to expect next.  For example consider the following sections:
a.      Title page (the title of the document, the author);
b.      Revision table (who worked on the document, when, why, what did they add to it?);
c.       Table of contents;
d.      Introduction or Summary;
e.      The body of the document;
f.        Glossary of terms.

Happy Writing!

EL

No comments:

Post a Comment