Verifying that it works.
WHAT TO TEST
- Accuracy: does it match reality
- Completeness: is anything missing
- Usability: can the reader complete the task
WHY USABILITY SEPARATELY
Accurate complete documentation can still be unusable.
HOW TO TEST ACCURACY
Follow it, exactly as written, on a real system.
WHY EXACTLY
Writers unconsciously perform steps they omitted.
WHO SHOULD TEST USABILITY
Someone representative of the reader.
WHAT TO DO
Give them the task and the document, and watch without helping.
WHY WITHOUT HELPING
Every intervention conceals a defect.
WHAT TO RECORD
Where they hesitate What they ask Where they go wrong What they skip
WHY HESITATION MATTERS
It indicates ambiguity even where they eventually proceed correctly.
WHAT TO FIX
Everything that caused difficulty.
WHAT REVIEW BY A SUBJECT EXPERT PROVIDES
Technical accuracy.
WHAT IT DOES NOT PROVIDE
Assurance that a non-expert can use it.
WHY
Experts cannot see missing assumptions.
WHAT TO ESTABLISH
Both kinds of review.
WHAT TO REVIEW FOR
Terminology consistency Structure consistency Broken links and references Outdated images Examples that no longer work
WHAT TO CHECK AFTER ANY SYSTEM CHANGE
Documentation affected by it.
WHAT TO ESTABLISH
That documentation is reviewed before release, not after.
WHY
Documentation published after a release is absent when users need it most.
