General Product Prose — Explaining How It Works
Priya writes to support: "My site was slow for a minute yesterday. Why didn't Nightjar alert me?" No step-by-step guide can answer that. She needs to understand how the product decides that a site is down. Pages that explain what a feature is, why it exists and how it behaves are the prose that holds the rest of the docs together.
The rule
Explain what it is, why it matters, then how it works.
General product prose covers overviews, concept pages, feature descriptions and glossary entries. It has no steps. Its reader wants a mental model: a picture of the product clear enough to predict what it will do. A good concept page follows a steady order:
- What it is: one plain sentence of definition.
- Why it matters: the problem it solves for the reader.
- How it works: the mechanism, at the depth the reader needs to predict behaviour, not the depth an engineer needs to build it.
- Limits and links: what it does not do, and where to go to act on it.
Here is Nightjar's concept page on incidents:
Incidents
An incident is Nightjar's record that a monitor is down. It exists so that you get one alert per outage, not one for every failed check. A check fails when your site does not respond within 30 seconds or responds with an error. Nightjar opens an incident when two checks in a row fail, each from a different region, which rules out a problem in a single network. It closes the incident as soon as a check succeeds and emails you how long the outage lasted.
A page that is slow but responds within 30 seconds counts as up. To choose who hears about incidents, see Set up alerts.
The shortcut
Apply the predict test: after reading, could the reader correctly predict what the product does in a situation the page never mentions? If not, the "how it works" part is missing something.
Define it
"An incident is Nightjar's record that a monitor is down." One sentence, no jargon.
The trap comes in two forms: marketing adjectives with no mechanism ("our intelligent incident engine"), and internal detail the reader cannot use, such as database tables and queue names.
Drills
Answer fast — trust the rule.
What does a reader want from a concept page?
In what order does the rule say to explain a feature?
A check from Mumbai fails, and the next check, from Frankfurt, succeeds. Under Nightjar's rule, what happens?
Which sentence belongs on a concept page for Nightjar users?
Remember
- Explain what it is, why it matters, then how it works.
- Shortcut: the predict test: can the reader foresee the product's behaviour in a new situation?
- Trap: adjectives with no mechanism, or internal detail the reader cannot use.