Top 7 Mistakes that Technical Writers Do

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.