Vinish Garg

Technical Writer. Published Author. http://www.vhite.com

Reviewing a Technical Document

with 3 comments

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 realised that organizations do not have detailed plans to train on ‘How to Review Documentation’.

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 paramters of TW?)

– 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.

Advertisements

Written by Vinish Garg

June 23, 2010 at 2:04 pm

3 Responses

Subscribe to comments with RSS.

  1. thanks for this informative post

    Kumar Chetan Sharma

    June 23, 2010 at 6:59 pm

  2. Chetan, you are always welcome (during working hours though:) )

    Vinish

    June 23, 2010 at 8:36 pm

  3. Nice one Vinish. Keep writing so that we can continue learning 🙂

    deepsishere

    June 26, 2013 at 2:12 pm


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: