Reference documentation is writing organized for lookup rather than reading — the dictionary, the API reference, the configuration guide, the glossary. Its readers know what they’re looking for; they need to find it quickly, get the answer, and return to their work.
Reference documentation is distinguished from procedural documentation and tutorials by its structure. Procedures are ordered by task sequence; tutorials are ordered by learning progression; reference documentation is ordered by the system’s structure — alphabetically, by component, by function, by parameter. The organizing principle is findability, not narrative.
Effective reference documentation provides, for each entry:
- Name — the exact term, command, parameter, or component being documented.
- Description — what it does, stated concisely. One or two sentences for simple entries; a paragraph for complex ones.
- Syntax or usage — the exact form. For code: the function signature. For a configuration setting: the valid values. For a concept: the definition.
- Parameters or attributes — what the entry accepts or contains, with types and defaults.
- Examples — at least one example showing the entry in use. Examples are not optional; they are often the first thing the reader looks at.
- Related entries — links to entries that the reader might also need.
The challenge of reference documentation is balancing completeness with usability. A reference that omits entries is unreliable — the reader can’t trust it to have what they need. But a reference that buries important entries in noise is equally unusable. Consistent structure, clear naming, and good search or navigation solve this: when every entry follows the same pattern, the reader learns to scan efficiently.
Related terms
- API documentation — the most common form of reference documentation in software
- procedural documentation — organized by task rather than by structure
- tutorial — organized by learning progression
- information architecture — the organizational principles that make reference documentation findable