# Writing the docs

Cicadel's docs should feel fast. A reader should understand a page by skimming it,
then succeed by following it. This guide sets the voice, the shape of a page and
the rules that keep the docs tested.

## Voice

Write like a senior engineer explaining something to a friend.

- **Short sentences.** One idea per sentence. Aim for fewer than 20 words.
- **Short paragraphs.** Two or three sentences. Then a break, a list or code.
- **Plain words.** "Use", not "utilize". "Start", not "initialize". "Run", not "execute".
- **Second person, active voice.** "You register the app." Not "The app is registered."
- **Present tense.** "Cicadel checks the routes." Not "Cicadel will check the routes."
- **Say what it does first, then why.** Lead with the outcome. Follow with the reason.
- **No hedging and no hype.** Drop "simply", "just", "easily", "powerful" and "seamless".
- **Cicadel first, Django second.** Explain each idea on its own terms. Cicadel is
  inspired by Django, not defined by it: mention Django only when the comparison
  helps a reader who knows it. Familiar words (apps, models, migrations, views,
  URLs, forms, middleware) keep their usual meaning.

## Shape of a page

1. **Title.** A noun for a concept ("Events") or a task for a how-to ("Serve static files").
2. **Lede.** One or two sentences under the title. What it is and when you need it.
3. **The smallest working example.** Show code early. Explain after.
4. **Sections that each answer one question.** Headings are short and scannable.
5. **Details last.** Edge cases, limits and reference tables go at the end.

Prefer lists and tables over long paragraphs. Use numbered lists for steps a reader
must follow in order.

## Callouts

Use GitHub alert syntax. The site renders each one as a callout.

```text
> [!NOTE]
> Rendered as "Good to know". Use it for helpful context.

> [!TIP]
> A shortcut or a better way to do something.

> [!WARNING]
> Something that can lose data, break a deploy or weaken security.
```

Keep callouts rare: at most a few per page. If everything is highlighted, nothing is.

## Diagrams

Put diagrams in `docs/diagrams/NAME.svg` and reference them with
`![Description](diagrams/NAME.svg)`. The site inlines the SVG so it follows the
light and dark themes. In the SVG, style shapes through classes that read CSS
variables with fallbacks, as in `docs/diagrams/request-lifecycle.svg`:
`--diagram-box`, `--diagram-hot`, `--diagram-line`, `--diagram-text`,
`--diagram-muted` and `--accent`. Give every diagram a `<title>` and `<desc>`.

## Rules that keep the docs tested

- **Tested snippets are code.** A fenced block directly after `<!-- example: PATH -->`
  or `<!-- file: PATH -->` is compiled and run by the test suites. Change it only
  together with its tests. Never separate the marker from its fence.
- **Linked headings are addresses.** Other pages link to some headings, for example
  `releases.md#stability-guarantee`. Renaming a heading changes its anchor. Search
  for `FILE.md#` before renaming, and update every link.
- **Facts come from the code.** Never document behavior you did not find in the
  code or its tests. Prefer leaving a sentence out to guessing.
- **Version strings follow the release.** Do not hard-code "no releases yet" or a
  specific version in prose that outlives the next release.

## Check your change

From `website/`, run `npm run build` and `npm run check`. From the repository root,
run `python3 website/scripts/test-examples.py` when you touch a tested snippet.