Reviewing Technical Documentation

June 23, 2010 at technical communication

While training new technical writers, many organizations focus their training efforts on Developing the documentation which is primarily about writing procedures, topics and instructions. The writers are also introduced to documentation process, style guides and templates but I have realized that organizations do not have detailed processes on reviewing documentation.

Documentation Reviewing

Reviewing is as important as writing and I always emphasize that reviewing skills are as important as documentation skills. For less experienced tech writers in my team, I tell them to revise the User Guides multiple times, for:

  • completeness (are all features covered/explained?)
  • UI texts (are all UI texts such as fields, buttons and tabs correctly referred to in the document?)
  • graphics (does the text on images make sense?)
  • clarity of language (are instructions clear?)
  • correctness of language (is the language correct for tense, punctuation, sentence structure, grammar, and other industry recommended guidelines and conventions for technical writers?)
  • accuracy of instructions (no stories and no emotional connection, ensure conciseness and ‘problem resolution’ aspects of procedures and instructions)
  • additional elements (notes, cautions, confirmation messages)
  • consistency (adherence to style guide, conventions )
  • template (layout for space, margins, style guide and conventions which includes typography, colors and icons)
  • TOC (logical, complete)
  • cross-references
  • index (accurate, comprehensive)
  • others (document properties, disclaimers and copyrights, title page, headers and footers, date, version, author name)
  • review complete package for everything
  • review
  • review
  • And again Review

A technical writer should always have a checklist for different aspects of document review.