10 Commandments For Technical Writers

The main goal of a technical writer is to convey an idea in a terse and concise way. A good technical writer need not be a Masters in English or Communications. All a technical writer needs is a clear understanding of the software/product/application and basic grammatical knowledge. We are here to make your technical writing job easier by presenting the 10 Commandments for Technical Writers.
1. Understand your Goal
Before you start writing, try to understand the goal of the technical document you are planning to write. Ask yourself “What you will write” and “Why are you writing it?” When you get the answer, start making the outline of the technical document.
2. Know your reader
The main purpose of a technical document is to serve its reader. So, it is very important to identify your reader. Remember that your reader is someone does not know about your product/application and this is the reason he/she is reading the document. Concentrate on the key ideas that the reader will look for in the document. Plan it accordingly.
3. Plan the flow of Information
Once you have planned the structure of the document, think about the flow. Decide which sections the document should contain and write a little outline of each section as well as its subsections. Plan it in such a way that your reader move from familiar information to new information. Moreover, never write the document in first person, use third person while narrating. Make your writing to the point. Delete anything that does not support your point.
4. Use a template
A good technical writing is done on a template. A template contains paragraph styles, layout for every page element such as headers, footers, headings, tables, paragraphs, steps, notes, precautionary messages, etc. It also contains every book element like front cover, title page, TOC, chapters, glossary, back cover, etc. Apart from all these, a document written on a template is easy for the reader to read and to edit it in future.
Templates are reusable. Design it once and use it when required. This will save time and money.
5. Add a nomenclature section
Always add a nomenclature section in the beginning of the document and use the said naming conventions consistently. It is always better to name a concept based on what it does. Apply this for the file-naming convention too. Always name figures or diagrams and give a good caption. This may contain multiple sentences which provide context and explanation. Moreover, do not use different terms for the same concept. You can use synonyms to distinguish concepts that are unrelated.
6. Use Tables, TOC, Glossary, x-refs and caption numbers
A good technical writer always summarise procedures in a table. Name the table and give a description for it. Include a glossary as the technical terms may confuse the reader. A glossary is useful in this case.
Make it a habit to create table of contents (TOC), cross-references (x-refs), and caption numbers electronically rather than typing them. Number all the equations in the document, even if there is only one equation in the document.
7. Be consistent
Always be consistent; be it in style, selection of words (British or American), numbering system, naming of concepts etc. Make it a point to refer each significant character (algorithm, concept, language) using the same word everywhere. Give a significant new character a proper name. Moreover, stick to one tense as it brings clarity and allows the reader to skim along.
8. Follow basic grammar rules
Put the concepts and all important terms in subjects. Then join each subject to a verb that expresses a significant action. Always prefer singular to plural number. To distinguish one-to-one relationships from n-to-m relationships, refer to each item in the singular.
Do not use passive voice. Use past tense when describing an experiment or some other action that occurred in the past.
9. Avoid acronyms and abbreviations
In technical writing, avoid acronyms and abbreviations. If you are using them, clarify the acronyms and abbreviations the very first time these are used.
10. Proofread
Do not forget to proofread the document you just created. You can ask one of the team members to read it aloud for you. Rewrite words/ phrases/sentences that you find confusing. Look at the style and the structure from the user’s point of view. Do a double spell-check, replace contractions and look for punctuation errors. Do not use jargons and colloquial English.