10 commandments for technical writers

The main objective of a technical writer is to convey an idea in a concise and concise manner. A good technical writer does not need to be a teacher in English or communications. All a technical writer needs is a clear understanding of the software / product / application and basic grammar knowledge. We are here to facilitate your technical writing work by presenting the 10 Commandments for technical writers.

1. Understand your goal

Before you start writing, try to understand the purpose of the technical document you plan to write. Ask yourself "What are you going to write" and "Why are you writing it?" When you get the answer, start drafting the technical document.

2. Know your reader

The main objective 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 you 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 family information to new information. Also, never write the document in the first person, use the third person while narrating. Make your writing to the point. Remove everything that is not compatible with your point.

4. Use a template

A good technical writing is done in a template. A template contains paragraph styles, design for each page element, such as headers, footers, headings, 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. In addition to all this, a document written in a template is easy to read and edit in the future.

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

5. Add a nomenclature section

Always add a naming section at the beginning of the document and use these naming conventions consistently. It is always better to name a concept based on what you do. Apply this also for the file naming convention. Always name figures or diagrams and give a good title. This may 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, 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. A glossary is useful in this case.

Get used to creating a table of contents (TOC), cross references (x-refs) and subtitle numbers electronically instead of writing them. Number all the equations in the document, even if there is only one equation in the document.

7. Be consistent

Always be consistent; whether in style, word selection (British or American), numbering system, concept designation, etc. Be sure to refer to each significant character (algorithm, concept, language) using the same word everywhere. Give a new and meaningful character a proper name. Also, keep a tense time, as it brings clarity and allows the reader to read it.

8. Follow the basic grammar rules

Put the concepts and all important terms in the subjects. Then link 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 n-m relationships, see each element in the singular.

Do not use passive voice. Use past when describing an experiment or some other action that happened 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 check 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. Perform a double spell check, replace the contractions and look for punctuation errors. Do not use slang and colloquial English.

If you impoverishment to enjoy the Pleasing Chronicle: Making money in the assuage of your own habitation writing online, then this is for YOU!: Click Here