soldermaskdocs

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.

KindThe reader isThe page isHere
Tutoriallearninga lesson that ends in a working boardYour first board
How-todoing a tasknumbered steps, the goal in the titleDeploy
Referencelooking something uptables of every key, flag and fieldCommand line
Explanationtrying to understandthe why, the design, the trade-offsRoutability

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

  1. Open with what the page lets you do, in one or two sentences.
  2. At most 25 words a sentence. One idea each.
  3. 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.
  4. Put keys, settings and numbers in tables.
  5. Write a task as numbered steps, one action each. Say what the reader should see.
  6. Put a caveat in a callout (!!! note, !!! warning), not in the middle of a sentence.
  7. Name things as the screen names them, in bold: Rebuild, Place again.
  8. No em dashes. Use a full stop, a colon, a comma or brackets. The landing follows the same rule.
  9. Keep every anchor another page links to. Renaming a heading renames its anchor.
  10. 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 writeThe public site shows
A first paragraph of one or two plain sentences, at most 40 words, with no links, code or boldThat 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.ymlNothing 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.

PagesWhy
research/*Research write-ups. A number stands with its date and its evidence.
pipeline/routability.mdThe model's page. Its correction block at the top withdraws numbers in place.
development/*, except this pageNotes 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.

CheckWhat the test does
The page existsEvery name in STYLED is a file under docs/.
Rule 1The 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 2No sentence over 25 words. A code span or a key counts as one word, and a link counts as its text.
Rule 3No since, until or as of followed by a date, such as 12 Sep 2026 or 2026-09-12. Other history is not caught.
Rule 8No em dash outside a code span.
AnchorsOn 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.py

When 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:

On this page