The main goal of a technical writer is to convey an idea in a concise 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 grammar skills. We are here to facilitate your technical writing job 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 will you write?” And “Why are you writing it?” When you get the answer, start outlining the whitepaper.
2. Know your reader
The main purpose of a whitepaper is to serve its reader. So, it is very important to identify your reader. Remember that your reader is someone who does not know your product / application and this is why they are reading the document. Focus on the key ideas the reader will be looking for in the document. Plan accordingly.
3. Plan the flow of information
Once you’ve planned the structure of your document, think about the flow. Decide which sections the document should contain and write a short outline of each section, as well as its subsections. Plan it in such a way that your reader moves from familiar to new information. Also, never write the document in the first person, use third person while narrating. Get 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 element on the page, such as headers, footers, headers, tables, paragraphs, steps, notes, caution messages, etc. It also contains all the elements of the book, such as the cover, title page, table of contents, 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 necessary. This will save you time and money.
5. Add a naming section
Always add a naming section at the beginning of the document and use the mentioned naming conventions consistently. It is 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 give 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, x-references, and subtitle numbers
A good technical writer always summarizes the procedures in a table. Name the table and give it a description. Include a glossary as technical terms can confuse the reader. In this case, a glossary is helpful.
Get in the habit of creating tables of contents (TOC), cross-references (x-references), and subtitle numbers electronically instead of typing them. Number all equations in the document, even if there is only one equation in the document.
7. Be consistent
Always be consistent; be it in style, word selection (British or American), numbering system, concept naming, etc. Be sure to refer to every significant character (algorithm, concept, language) using the same word everywhere. Give a significant new character a proper name. Also, focus on a tense as it brings clarity and allows the reader to read it.
8. Follow the basic grammar rules
Put the concepts and all the important terms in subjects. Then match each subject to a verb that expresses a meaningful action. Always prefer the singular number to the plural. To distinguish one-to-one relationships from nam relationships, query each element in the singular.
Don’t use passive voice. Use last 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, please clarify the acronyms and abbreviations the first time you use them.
10. Review
Be sure to review the document you just created. You can ask one of the team members to read it aloud. Rewrite the words / phrases / sentences that are confusing to you. Look at the style and structure from the user’s point of view. Do a double spell check, replace contractions, and look for punctuation errors. Don’t use slang or colloquial English.