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