Top 7 Mistakes that Technical Writers do!
Technical Writing is a very niche
field. Apart from the Style Guides, there is no rule book which documents the
best practices to be followed as a Technical Writer. How easy it would be if
someone could document the tips and tricks to be followed in this profession
and make life easier.
Here are the top 7 mistakes that
any Technical Writer is likely to make and how to avoid it:
Getting overwhelmed by the product/technology: Accept the fact that
you cannot learn a product within a month of joining a company. It takes a
maximum of 1 year to know any product in and out (assuming it is an enterprise
product). It is a big learning curve! First get the big picture, say for
example there are 4 main modules of a product. Understand how each module is
connected to the other to make a complete product on a very high level. Then
dig deep in to each of the modules for a clear and better understanding.
Inappropriately arranged content: Documentation plays a major role
in reducing support calls. The information should be readily and quickly
available when needed. Therefore there is a greater need to arrange the content
in a TOC applying proper headings. Headings compartmentalize the content, which
is easier to read from the end user perspective. You can have maximum 3 levels
of heading and sub-headings. For example, heading1, heading2, and heading3.
Using long sentences and difficult words: Use common words instead
of difficult words. For example, using (quiet, modest or reserved) instead of
demure. One of the best practices is to use a Word Web installed on your laptop.
That way you can do a quick search on Word Web (or any online dictionary) and get
synonyms for difficult words, and use those words instead. Use shorter
sentences. As a thumb rule, break sentences which run into more than 2 lines.
Incorrect illustrations: If you are not good at drawing diagrams,
then it is better to delegate it to someone who is good with illustrations.
Incorrect illustrations or bad diagrams often confuses the audience.
Inconsistent usage of style: Every organization has their own
styles defined for documentation. Using inconsistent style often confuses the
audience while performing procedural steps. For example, using bullet points
under numbered list or inconsistent usage of bold or italics in procedural
steps.
No Proofreading or Peer review done: There is a famous saying “Four
eyes are better than two”. Thumb rule is to first proofread the document
yourself once you are done with the writing. When proofreading, it is better to
read it aloud to pick grammatical errors. Then if possible, get it also peer
reviewed by one of your team members or colleagues. Peer review is generally
done for larger chunks of content.
Grammar and Punctuation Errors: A complete sentence should have a subject
and a main verb and the verb should be in agreement with the subject. For
example, if the subject is singular, the verb should also be singular. Whereas
if the subject is plural, the verb should also be plural. Always use active
voice and proper tense like, past tense, present tense, future tense depending
upon the subject and verb. You can refer to Wren and Martin book to improve
your grammar. Using correct punctuation like comma, period, apostrophe, etc. in
sentences is also very important.
Hope this blog helped someone in
their profession as a Technical Writer.
