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.

> [!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.