Helping when things go wrong.
WHY IT MATTERS
Readers arrive at documentation most often when something has failed.
WHAT TO DOCUMENT
The error, as it actually appears What it means What causes it How to resolve it
WHY AS IT APPEARS
Readers search for the exact text they are seeing.
WHAT TO INCLUDE
The exact message, verbatim.
WHY VERBATIM
Paraphrased errors cannot be found by searching.
WHAT TO ORGANISE BY
The symptom the reader observes.
WHY NOT BY CAUSE
Readers know what they are seeing, not why.
WHAT A TROUBLESHOOTING ENTRY SHOULD CONTAIN
The symptom The likely causes, in order of likelihood How to check each How to resolve each What to do if none apply
WHY IN ORDER OF LIKELIHOOD
It resolves most cases fastest.
WHAT TO INCLUDE
How to establish which cause applies.
WHY
Listing causes without a way to distinguish them leaves the reader guessing.
WHAT TO PROVIDE
What to do when nothing works.
WHAT THAT MEANS
Who to contact, and what information to provide.
WHY THAT INFORMATION
It prevents the exchange where support asks for details the reader could have gathered.
WHAT TO ASK FOR
Version, configuration, what was attempted, exact error, when it started.
WHAT TO BUILD FROM
Actual support requests.
WHY
They are the record of what readers actually encounter.
WHAT TO TRACK
Questions asked repeatedly.
WHAT TO DO
Document each one.
