Making documentation usable.
WHAT A PROCEDURE SHOULD CONTAIN
What it achieves When it applies What is needed before starting The steps, in order What the result should look like What can go wrong and what to do Who to ask
WHAT MAKES ONE USABLE
Short Specific Written for whoever performs it Available where the work happens Current
WHY WHERE THE WORK HAPPENS
A procedure in a folder in an office is not used at a machine.
WHAT MAKES ONE USELESS
Length Abstraction and general statements Describing what should happen rather than what does Stored where nobody looks
WHY ASPIRATIONAL PROCEDURES FAIL
They are ignored, and they undermine confidence in all documentation.
WHO SHOULD WRITE IT
The person who does the work.
WHY
They know the reality, including the steps nobody else sees.
WHAT TO DO AFTER WRITING
Have someone else follow it, without help.
WHAT THAT REVEALS
Every assumption, missing step and piece of unstated knowledge.
WHAT TO ADD
Whatever they had to ask.
WHAT FORMAT TO USE
Numbered steps, in the order performed.
WHAT TO ADD WHERE HELPFUL
Photographs of the actual equipment, screens or correct result.
WHY PHOTOGRAPHS
They remove ambiguity that words cannot.
WHAT TO AVOID
Explaining background before the steps Combining several tasks in one document
WHY SEPARATE DOCUMENTS
People look for one task.
WHAT TO TEST
Whether anyone actually uses it.
