Primary user need: I need to look something up.
Reference documentation describes the product accurately and in a form that supports quick retrieval. The system itself determines the scope: settings, commands, parameters, configuration values, API fields, options, limits and compatibility information.
The original framing tied reference to the structure of the code. We broaden that: reference should reflect the structure of whatever is being described, which might be code or API structure, dashboard hierarchy, settings groups, commands, product features or a configuration model.
A brief explanatory context is acceptable. Extended discussion of why something works the way it does belongs in explanation. Full task instructions belong in a how-to guide.
Common failures: burying lookup information inside prose, formatting comparable entries inconsistently, and letting reference turn into a collection of small tutorials.
Worked example
Before
Rate limits
Most customers will find that the standard rate limit is generous enough for typical use. On the Team plan you get quite a lot more, and Enterprise customers should speak to their account manager, though as a rule the ceiling is much higher there. Bursts are tolerated to a degree.
After
Rate limits
Requests per minute, per API key:
- Free: 60
- Team: 600
- Enterprise: negotiated, 6,000 by default
Burst allowance is 2x the limit for 10 seconds. Exceeding it returns 429 with a Retry-After header.
