write-docs

Write docs that teach

Turn reference material into documentation that teaches. The standard is the FastAPI docs: every concept has a motivation, every rule has a real code example, complexity grows page by page. The voice is human prose in the project's language — never telegraphic bullets.

Workflow

1. Read before writing

• Find the style template. If the user already likes a page on this site, inherit its voice, section order, and component usage. If nothing exists, use the FastAPI docs as the reference standard.
• Read the real code you will document. Open every file you quote. Never invent signatures, file names, or export lists.
• Read the neighboring pages. Reuse their terminology — one word per concept — and collect their anchors for cross-links.
• Check the docs-site component API in the installed version. Component names change between releases (Starlight 0.38 exports Aside, not Callout). Import from the package, not from memory.

2. Ask only what changes the deliverable

Before a large rewrite, clarify format decisions only: page format (pure docs page, or docs plus a copyable artifact?), language of embedded artifacts, target frameworks. Do not re-ask questions the existing pages already answer.

3. Write the full draft in one pass

Write the complete page, verify it, then show it. A partial draft hides structure problems. Never cut the draft in half on your own: tutorials earn their length (FastAPI standard); READMEs stay short — that is a different artifact.

4. Verify before reporting

Run the docs build, check anchors, re-read snippets — see the checklist at the end of this file.

Style rules

Motivation before rules. Explain the pain before the solution. A rule without a reason is decoration; readers skip it. Open with the problem, then show how the rule removes it.

Human prose, not telegraph. Write full sentences. Replace label-style fragments («Границы. Код инфраструктуры. Меняется редко.») with sentences. Drop «В этом разделе мы рассмотрим…» filler — start with substance.

One end-to-end example. Pick one real feature from the project and thread it through all pages. The reader follows a single codepath from the UI to the data source. Number its files when listing them; trace one user action through every layer at the end.

Real code only. Snippets come from files opened this session. If an example needs a function, find its real signature — even the argument count must match. Pseudocode is a last resort and is marked as such.

❌ → ✅ patterns. When a rule can be broken, show the broken code, name the concrete consequence (bundle leak, broken build, stale link), then show the fix. Two short code blocks beat a paragraph of theory — but keep the pattern rare: one, at most two pairs per page, only for the rules readers actually break. A page that turns into a ❌/✅ catalogue loses its narrative; for every other violation, name it and its consequence in prose. (2026-10-07, user: «на вот этом паттерне ❌/✅ не зацикливайся… этот паттерн надо использовать меньше».)

Tables for decisions, prose for reasoning. Use tables for mappings and «куда положить X» choices. Use paragraphs for why the rules exist.

Honest limits. Close with what the system does not do: where it is not a linter, where quality depends on the model, what stays manual. Admitted gaps build trust; fake completeness breaks it.

Fix stale facts while you are there. Dead links, renamed repos, folders that do not exist, planned features marked as ready — verify each claim against the repository. An honest «🚧 в работе» beats a silent wrong status.

One term per concept across the whole site. When a concept gets renamed on one page, sweep every page and the sidebar config. Half-renamed terminology confuses search and readers.

Page anatomy

Order sections so each one answers the reader's next question:

1. Intro — what the reader gets from this page, 2–4 sentences.
2. Motivation — the problem narrative: how the project looks without this solution.
3. Concepts and rules — one section per concept, each with a small real example.
4. Worked example — the end-to-end feature, file by file, plus the traced data flow.
5. Violations and fixes — the one or two rules most often broken, as ❌ → ✅ pairs; the rest as prose with named consequences.
6. FAQ or checklist — recurring questions with short answers and code.
7. What's next — cross-links to related pages with one-line hooks.

Not every page needs every section. Keep the order, drop what does not apply.

Docs-site specifics (Starlight)

Gotchas that cost debugging time once — do not repeat:

• Starlight 0.38 exports Aside, not Callout. Types: note, tip, caution, danger.
• Steps requires a markdown ordered list inside (1. **Заголовок** plus indented content). Custom step components fail the build.
• Tabs / TabItem hold framework or stack variants of the same instruction.
• Nested code fences in MDX: wrap the outer block in four backticks (````markdown).
• Emoji headings produce slugs with a leading hyphen (## 🚀 Быстрый старт → #-быстрый-старт); emoji with VS16 keep the selector in the slug. Copy anchors from the built HTML, never guess them.
• Keep the house conventions of existing pages: emoji in section headers, in-page links to related sections, «Что дальше» / «Следующие шаги» at the end.

Scope split

This skill writes teaching docs. A README is a different artifact: one screen, centered header, badges, quick start, links. If the task is a README, suggest the beautify-github-readme skill instead.

Verification checklist

Before reporting done:

• Build passes (exit 0); page count matches the site norm.
• Every anchor link matches an id in the built HTML.
• Every code snippet was read from the source file this session.
• No invented signatures, no stale links, no wrong statuses.
• Every rule has a reason; every example comes from the real project.
• Terms are consistent across every rewritten page.