July 3, 2012

Characters of a good technical document

A Good technical document

I believe a “good” word is respective, anything good for me may not for you. But to qualify to be a good technical document I think minimum these qualifications should be there. Many writers had written their view, here is my two cent.:

1.     Accurate
-          Correct information.
-          Many contracts have been lost over one too many factual mistakes in the documentation.
-          Get your drafts reviewed by people whose review is meaningful.

2.     Complete
-          Don’t give an overview of a procedure if users need minute detail.
-          Editing.
-          Proofreading.

3.     Consistent
-          Anytime you use a different word or term to refer to something you’ve already called by another name, you risk confusing the readers.

4.     Clear
-          Write clearly
-          Use simple words and short sentences (KISS-Keep it simple)

5.     Useful
-          Is it easy to learn? Is it efficient to use? Can a user recover quickly from errors? Is it easy to remember what to do? Is it fun to use?
-          Does my document make it easy to find the information the user needs? (index, TOC)
-          If the software has less-than optimal usability, the documentation must try to make up for it.
-          Documentation must also be tested.

6.     Attractive
-          The document should be attractive to the eye.
-          Readers resist reading what they don’t like to look at.

7.     Navigation & Search
-          The topics should be easily searchable.
-          Readers must have comfort to navigate easily in a document.

Related Links:

Post a Comment