Writing Docs
The Writing Docs skill holds the workflow for scoping, explaining and reviewing documentation, together with its quickstart, voice and mechanical rules.
Read the skill
Read the complete Writing Docs skill before writing or editing a page, README or guide. It is the authoritative writing guidance for contributors and agents; the checked limits below are published here for reference.
Limits
The docs checks read these from tests/docs/limits.toml, and fail when
this table differs from it. A file past its line limit is listed in
tests/docs/large-files.toml, and so is a page written before the
shape rules: each may shrink, never grow.
| Limit | At most | Why |
|---|---|---|
| Characters in a table cell | 60 | A cell is a few words; more is a section. |
| Headings under a heading, and at a page's top | 10 | Group a longer list a level deeper. |
| Characters in a hook | 45 | It's a heading, and half the tab's title. |
| Words in a README outside docs/ | 120 | A README is a map; how it works is a page. |
| Characters in a list item | 400 | An item is a line or two; more is a section. |
| Lines in a Markdown file | 500 | Split a longer page by subject. |
| Pages under a page in the site's tree | 10 | Group a longer list in a folder. |
| Characters in a paragraph | 600 | More is two subjects: two sections. |
| Links under a README's ## Code | 5 | Name the entry points, three or so. |
| Lines in a Rust file | 1,000 | Split where a responsibility ends. |
| Characters a section's lone paragraph has at least | 80 | Less is too thin to stand alone: fold it in. |