10 commandments for technical writers
The main goal of a technical writer is to convey an idea in a short and concise manner. 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’re here to make your technical writing job easier by introducing 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 whitepaper outline.
2. Know your reader
The main purpose of a technical document 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. 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. Make your writing to the point. Delete anything that doesn’t 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 book elements like 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 nomenclature section
Always add a naming section at the beginning of the document and use those naming conventions consistently. It is always better to name a concept based on what it does. Apply this also for the file naming convention. Always name figures or diagrams and provide a good legend. This can contain multiple sentences that provide context and explanation. Also, don’t 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 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 TOCs, cross-references (x-refs), and subheading numbers electronically instead of writing them down. 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, 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 the concepts and all the important terms in 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.
Don’t forget to review the document you just created. You can ask one of the team members to read it out loud 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 check for punctuation errors. Do not use slang and colloquial English.