Writing docs
Written by charter docs (the same page in every repo that uses it): don’t edit it here, change cmd/charter/docs/writing.md in charter. mise run docs:lint checks what a program can; mise run docs:review has Claude check the rest.
The reader
Someone who wants to use this, or to help with it, and has a job to do. Write for that job. The docs are not a record of how the project was built: git history and the issues hold that.
The rules
- Short. Steps and commands first, one sentence of why where it matters. If a paragraph does not change what the reader does, cut it.
- True at this commit. No history (“previously”, “we changed”), no plans: plans are GitHub issues.
- Checkable. Every command is real and pasteable. Every path exists. Every number says where and when it was measured.
- One place per fact. Other pages link to it.
- Honest about limits, next to the claim they limit.
- Plain words, one name per thing. Tables for mappings, bullets for lists, code blocks for commands.
The layout
| Section | What goes there | Size |
|---|---|---|
Home (README.md) | What this is, what you get, the map, what is generated, the index | One screen |
| Getting started | From nothing to a working result, every step run as written | One page |
| Guides | One job per page: steps and commands | Up to about 500 words each |
| Reference | Commands, tasks, packages: tables, one line per row | As long as the tables are |
| How to help | Setting up, reporting a bug, the rules, upstream issues, benchmarks | A few short pages |
A page belongs to one section. Nothing a user needs lives only under How to help.
The mechanics
- Front matter first:
title,nav_order, andparentunder another page. The home page also haspermalink: /. - Links are relative, and an anchor must match a heading. A new page gets a row in the home page’s index.
- No two opening curly braces together, and no curly brace followed by a percent sign: the site’s renderer reads them as template code.
- No release version in a page: link
releases/latest, write@latest, or usevX.Y.Z. - Don’t edit what is generated:
_config.yml,_sass/,llms.txt, this page, and the pages_generated.tomllists (change the code their command reads). The home page’s “What is generated” table lists them.
When the code changes
The page changes in the same commit, and a removed thing is removed from every page (mise run docs:lint finds the mentions).