Information looked up rather than read.
WHAT REFERENCE MATERIAL IS
Information consulted at a specific point of need.
WHAT IT COVERS
Settings and their effects Commands and their options Interfaces and their parameters Codes and their meanings Specifications and limits
WHAT IT MUST BE
Complete Accurate Consistently structured Findable
WHY CONSISTENCY MATTERS MOST
Readers learn the structure and then navigate by it.
WHAT TO ESTABLISH
A standard structure for each entry, applied uniformly.
WHAT AN ENTRY SHOULD CONTAIN
What it is What it does Accepted values or format Default value Effect of each value Constraints and dependencies An example
WHY EXAMPLES MATTER MOST
They resolve ambiguity faster than description.
WHAT TO PROVIDE
A realistic example, not a placeholder.
WHY REALISTIC
Placeholders leave readers guessing at format.
WHAT TO STATE ABOUT DEFAULTS
What happens if the value is not set.
WHY
It is the commonest question.
WHAT TO DOCUMENT ABOUT DEPENDENCIES
What must also be configured What conflicts
WHY
Settings that require others fail confusingly.
WHAT TO AVOID
Reference entries that describe without explaining the effect Undocumented options Documentation that lists parameters without saying when to use them
WHAT TO ESTABLISH
That reference material is generated from or checked against the actual implementation.
WHY
Reference documentation drifts from reality faster than any other kind.
WHAT TO VERIFY
Every stated value and default.
