Writing the manual
These are the rules for the manual's pages under docs/. The manual is for
someone using soldermask: it says what is true now and how to do things. The
research log is CHANGELOG.md, and it keeps its own voice.
One page, one job
Documentation comes in four kinds, and a page that mixes them serves nobody. The split is Diátaxis.
| Kind | The reader is | The page is | Here |
|---|---|---|---|
| Tutorial | learning | a lesson that ends in a working board | Your first board |
| How-to | doing a task | numbered steps, the goal in the title | Deploy |
| Reference | looking something up | tables of every key, flag and field | Command line |
| Explanation | trying to understand | the why, the design, the trade-offs | Routability |
A long page can hold more than one kind if each section holds one. Workbench is reference tables with short tasks between them.
The rules
- Open with what the page lets you do, in one or two sentences.
- At most 25 words a sentence. One idea each.
- Say what is true now. Dates, replays and what was tried and dropped go in the CHANGELOG. Link to the entry when the reason matters.
- Put keys, settings and numbers in tables.
- Write a task as numbered steps, one action each. Say what the reader should see.
- Put a caveat in a callout (
!!! note,!!! warning), not in the middle of a sentence. - Name things as the screen names them, in bold: Rebuild, Place again.
- No em dashes. Use a full stop, a colon, a comma or brackets. The landing follows the same rule.
- Keep every anchor another page links to. Renaming a heading renames its anchor.
- Every number is still measured. The manual states it; the CHANGELOG holds the evidence.
How the public site uses a page
The public site (Fumadocs) is built from docs/ by
solderdocs/scripts/sync-docs.mjs. Three things it does with what you write:
| You write | The public site shows |
|---|---|
| A first paragraph of one or two plain sentences, at most 40 words, with no links, code or bold | That paragraph as the page's subtitle, in search results and on its share card |
| A card grid (below) | A grid of Fumadocs cards, each with its icon |
A new top-level section in mkdocs.yml | Nothing until it is added to a tab: the sync stops and names it |
A card grid is Material for MkDocs' own syntax, so the app's /docs draws it too:
<div class="grid cards" markdown>
- :material-download:{ .lg .middle } **[Install](getting-started/install.md)**
Install soldermask and check your setup.
</div>The icon must be in CARD_ICONS in the sync script, which maps it to a Lucide
icon. The sidebar switcher's tabs are TABS in the same script. Each tab has a
title, a one-line description, an icon, and the mkdocs.yml sections it holds.
Pages that keep the evidence voice
Some pages under docs/ are not manual pages, and these rules do not apply to
them. They keep the CHANGELOG's voice: a bolded claim, then what was measured,
on how many boards, against which baseline.
| Pages | Why |
|---|---|
research/* | Research write-ups. A number stands with its date and its evidence. |
pipeline/routability.md | The model's page. Its correction block at the top withdraws numbers in place. |
development/*, except this page | Notes for people working on the code. |
Do not rewrite one of these into the manual's voice, and do not add it to
STYLED. A dated claim there is history on purpose.
Checking a page
tests/test_docs_style.py checks every page in its STYLED list. It reads
paragraphs, list items and table cells. It skips headings, code blocks,
pictures, admonition lines and HTML comments.
| Check | What the test does |
|---|---|
| The page exists | Every name in STYLED is a file under docs/. |
| Rule 1 | The first thing under the title is a paragraph. A heading, picture, table, quote, list, code block or admonition fails. It does not judge what the paragraph says. |
| Rule 2 | No sentence over 25 words. A code span or a key counts as one word, and a link counts as its text. |
| Rule 3 | No since, until or as of followed by a date, such as 12 Sep 2026 or 2026-09-12. Other history is not caught. |
| Rule 8 | No em dash outside a code span. |
| Anchors | On every page, listed or not, a link to page.md#anchor lands on a heading or an explicit id. |
.venv/bin/python tests/test_docs_style.pyWhen you rewrite a manual page, add it to STYLED in the same change. The
manual pages not yet listed are the backlog.
For a case these rules do not cover, use one of these style guides: