Writing rules: Reference

Reference is information-oriented. The reader is working and needs a fact they can trust — the format of a field, the meaning of a status, the behaviour of a setting. Reference describes the machinery; it does not teach it or argue for it.

The reader

• Knows what they're looking for and wants to find it, trust it, and leave.
• Consults reference the way they'd consult a map: often, briefly, mid-task.

Rules

• Describe. State what things are, what they contain, what they do, and what constraints apply — accurately, completely, and nothing more.
• Be austere and neutral. One fact per statement, no persuasion, no personality.
• Structure the topic to mirror the product's own structure (screens, fields, statuses, settings in the order the application presents them), so the docs map onto what the reader sees.
• Be consistent — in headings, tables, terminology, and phrasing patterns — across the whole reference section; predictability is what makes reference usable.
• Examples are welcome as illustration of a described behaviour, not as a substitute for describing it.
• Basic usage statements are fine ("accepts a cron expression"); anything procedural beyond that links to a how-to guide.

Avoid

• Instructions and walkthroughs — link to how-to guides.
• Explaining why the design is the way it is — link to explanation.
• Opinions, recommendations, or marketing language.
• Letting entries drift out of date — wrong reference is worse than none.

Quality check

Could a reader land on any line of this topic mid-task, take it as fact, and act on it safely?