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.:
- Correct infor
- Many contracts have been lost over one too many factual mistakes in the documentation.
- Get your drafts reviewed by people whose review is meaningful.
- Don’t give an overview of a procedure if users need minute detail.
Anytime you use a different word or term to refer to something you’ve already called by another name, you risk confusing the readers.
- Write clearly
Use simple words and short sentences (KISS-Keep it simple)
- 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.
- The document should be attractive to the eye.
- Readers resist reading what they don’t like to look at.
- The topics should be easily searchable.
- Readers must have comfort to navigate easily in a document.