10 commandments for technical writers

The main goal of a technical writer is to convey an idea in a short and concise way. A good technical writer does not need to have a master’s degree 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 purpose of the whitepaper you plan to write. Ask yourself “What are you going to write” and “Why are you writing it?” When you get the answer, start making the outline of the whitepaper.

2. Know your reader

The main purpose of a whitepaper is to serve its reader. Therefore, it is very important to identify your reader. Remember that your reader is someone who does not know your product/application and this is the reason why they are reading the document. Focus on the key ideas that the reader will look for in the document. Please plan 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 short summary of each section, as well as its subsections. Plan it in such a way that your reader moves from familiar information to new information. Also, never write the document in the first person, use the third person when narrating. Keep your writing to the point. Delete anything that does not support your point.

4. Use a template

Good technical writing is done on a template. A template contains paragraph styles, layout for each page element such as headers, footers, headers, tables, paragraphs, steps, notes, caution messages, etc. It also contains all the elements of the book such as cover, title page, TOC, chapters, glossary, back cover, etc. Apart from all this, a document written in a template is easy for the reader to read and edit in the future.

The templates are reusable. Design it once and use it when needed. This will save time and money.

5. Add a naming section

Always add a naming section to the beginning of the document and use those naming conventions consistently. It’s always better to name a concept based on what it does. Apply this for the file naming convention as well. Always name figures or diagrams and provide a good legend. This can contain multiple sentences that provide context and explanation. Also, do not use different terms for the same concept. You can use synonyms to distinguish concepts that are not related.

6. Use tables, TOC, glossary, external references and subheading numbers

A good technical writer always summarizes the procedures in a table. He names the table and gives a description for it. Include a glossary as technical terms can confuse the reader. A glossary is useful in this case.

Get in the habit of creating tables of contents (TOCs), cross-references (x-refs), and caption numbers electronically instead of 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; either in style, choice of words (British or American), numbering system, naming of concepts, etc. Be sure to refer to each significant character (algorithm, concept, language) using the same word throughout. Give a new significant character a proper name. Also, stick to a tense, as it adds clarity and allows the reader to skim.

8. Follow basic grammar rules

Put concepts and all important terms into topics. Then match each subject to a verb that expresses a significant action. Always prefer the singular number to the plural. To distinguish one-to-one relationships from nam relationships, refer to each element in the singular.

Don’t use the passive voice. Spent past 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 acronyms and abbreviations the first time you use them.

10. Review

Don’t forget to review 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 structure from the user’s point of view. Double check spelling, replace contractions, and look for punctuation errors. Do not use slang and colloquial English.