We have mentioned in one of our blogs that technical writing is an art. We have also given you some tips and stated certain points which are to be kept in mind while writing a technical document. There are certain best practices we follow and we are sharing with you in this blog post. However, it has to be kept in mind that these practices are only suggestive possibilities for better technical documentation.
1. Understand the Product or Application
It is very important to understand the Product or Application you are writing about. Ask yourself “what”, “why”, “how”. Start with “what” followed by “why” and ending with “how”. Once you get the answer, start writing. If you are not sure about something related to the Product or Application, talk to the subject matter expert. Moreover, never repeat verbatim the words of the subject matter expert. Always ask for clarification as this is the only way to get right information. Do whatever it takes to ensure that each word, sentence and paragraph in the document is meaningful to everyone.
2. Identify the Reader
Now ask yourself again: Who will read it? When you get the answer, think about the main points that the reader will be looking for in the document. Based on these, structure the document and start writing.
3. Use a Template
Using a template saves time as well as money. If you design documents from scratch for every project, you are not only wasting time but money too as the time spent in designing is added to the cost of each project. Remember templates are reusable. Once you have created a set of templates, you never have to create them again. You can reuse them in every project after that.
Many people think that a template defines only the paragraph styles used in a document. In fact, a well-designed template contains not only paragraph styles, but also the 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. All of these elements require a great deal of thought and a lot of time to design so that the template is easy for the writer to use and easy for the reader to read.
4. Work with a Plan
Working with a plan, helps you save yourself from extra work later on. Your plan should include:
- List of the chapters that will be written
- Naming conventions that will be used
- Location in the network where the document will be stored
- Method by which the documentation will be delivered to the reader as well as method by which the customer will access the documentation
- Order in which the information is to be presented
5. Use Naming Convention
It is always a good practice to introduce the naming convention in the beginning of the document. It is always better to name a technique or section based on what it does rather than how it does it. Apply this for the file-naming convention too as the file-naming should make sense to you and to others. Creating a file-naming convention is one of the most considerate things you can do for the team.
6. Consistency
Whether it’s the formatting styles or the use of numbering systems, or the selection of words (British English or American English), you have to be consistent. Moreover, you have to stick to one tense.
7. Creation of Table of Contents, and adding Cross-References, and Caption Numbers
There are writers who type the table of contents (TOC), cross-references (x-refs), and caption numbers rather than letting the desktop publishing software create them. Creating these electronically makes it an easy task to update the document later on.
8. Include Glossary
Glossary and Index are must in technical documentation. Imagine you reading the document for the first time. Don’t you think the technical terms confuse you? A glossary comes handy in this case.
9. Versioning
It is a good idea to version a technical document. Versioning a document does not create confusion in future when the product or application has been updated and new information has to be added. Moreover, it helps to compare the updates made to the product or application over a period of time.
10. Proofreading
Always proofread the documents you create. Look at the style, spellings and the structure and read it from the user’s point of view. One good way of proofreading is to allow other members of the team to read it. If they find any sentences that they don’t understand, rewrite them.
Do a double spell-check and replace contractions. Look for punctuation errors. Follow a parallel structure in bulleted lists. Do not use a period after items in a bulleted list unless they are complete sentences. However, if the list contains a mixture of clauses and complete sentences, put a period at the end of each list item.
