Writing rules: Explanation

Explanation is understanding-oriented. The reader wants to deepen how they think about the system — often away from the keyboard entirely. It is discussion: context, background, reasoning, connections.

The reader

• Is reflecting, not working; nothing here is needed mid-task.
• Wants the bigger picture: why the system is shaped this way, how the pieces relate, what the trade-offs were.

Rules

• Bound the topic: a good explanation answers to a title like "About billing periods" or "Why readings are immutable". If "About…" doesn't fit, it probably isn't explanation.
• Provide context and background: history, constraints, the problem the design answers, how this connects to neighbouring concepts.
• Discuss alternatives and trade-offs. Opinions and recommendations are permitted here — and only here — provided they are clearly marked as judgement, with the reasoning shown.
• Approach the subject from the reader's perspective and interests, not the implementation's; it's fine to take a wider view than the product itself.
• Write in connected prose — this is the one quadrant where discussion, analogy, and even a little narrative serve the reader.
• Link to tutorials, how-to guides, and reference rather than absorbing their jobs.

Avoid

• Step-by-step instructions of any kind.
• Catalogues of facts, options, or field definitions — that is reference.
• Trying to make the reader do something; explanation has no task.

Quality check

Would a thoughtful user reading this over coffee come away understanding the system better — and trusting its design more — without once needing to touch the application?