Best practices in Technical Writing
- 2. Technical writing is writing on a specific subject for a specific purpose to a specific audience. Technical writers can be considered as a bridge between people who know technology and people who use it. They understand the complications of technology and put it in simple words that help the user understand and use the technology. User Manuals, Online help files, Reports, Proposals, Procedures, Release notes , Brochures, etc.
- 3. Audience analysis is most important consideration in planning, writing, and reviewing a document. To write effective documentation that suits the users, we must understand their needs. In other words, do not create a 300-page manual when a quick reference guide will do.
- 4. Technical writing is full of complex information. Do not confuse readers with heavy information. Write document to audience's readability level. Document should help the readers to complete their required task.
- 5. Use active voice to ensure that your readers and users clearly understand your documentation. It is commonly held that passive voice is acceptable in technical writing. However, overuse of passive voice, or use of passive voice in long and complicated sentences, can cause readers to lose interest or to become confused.
- 6. In technical writing, an advance organizer is a bulleted list at the beginning of a chapter that provides an overview of the chapter. The most important single factor influencing learning is what the learner already knows. Advance organizers help users process and retain information based on what they already know.
- 7. Break your documentation into smaller portions using bulleted lists, shorter paragraphs, and cross-references. Chunk your documents according to topics—one topic per chunk. Chunking keeps the readers' attention, providing them space to stop and absorb what they've read.
- 8. Too much text crammed onto a page intimidates readers and turns them away. In technical writing, always use white space around the text to break up pages. Too much text can tire the eyes.
- 9. Use cross-references to link related information that is described elsewhere in the document. Cross references are not essential to the current discussion. In online documentation, provide adequate hyperlinks to cross-reference related information.
- 10. Step/action tables provide a practical way to separate procedural steps from other descriptive information. This is a very important aspect of information mapping. Procedures contained in step/action tables are easy to read and follow, increasing document effectiveness.
- 11. A quick reference summarizes the most common user procedures, which is very helpful to users. A quick reference help readers get started without having to comprehend a large amount of information beforehand.