Best practices in Technical Writing


Published on

Best practices in Technical Writing by Atinder Sodhi in the TWB Alumni knowledge sharing session.

Published in: Education, Business

Best practices in Technical Writing

  1. 1. By: Atinder Sodhi
  2. 2. Technical writing is writing on a specific subject for aspecific purpose to a specific audience.Technical writers can be considered as a bridgebetween people who know technology and people whouse it.They understand the complications of technology andput it in simple words that help the user understand anduse the technology. User Manuals, Online helpfiles, Reports, Proposals, Procedures, Release notes, Brochures, etc.
  3. 3. Audience analysis is most important consideration inplanning, 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. 4. Technical writing is full of complex information.Do not confuse readers with heavy information.Write document to audiences readability level.Document should help the readers to complete their required task.
  5. 5. Use active voice to ensure that your readers and usersclearly understand your documentation.It is commonly held that passive voice is acceptable intechnical writing.However, overuse of passive voice,or use of passive voice in long andcomplicated sentences, can causereaders to lose interestor to become confused.
  6. 6. In technical writing, an advance organizer is a bulleted listat the beginning of a chapter that provides an overview ofthe 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. 7. Break your documentation into smaller portions using bulletedlists, 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 theyve read.
  8. 8. Too much text crammed onto a page intimidates readersand 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. 9. Use cross-references to link related information that isdescribed 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. 10. Step/action tables provide a practical way to separateprocedural 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. 11. A quick reference summarizes the most common userprocedures, which is very helpful to users.A quick reference help readers get started without having to comprehend a large amount of information beforehand.