Documentation style guide
How Glasnost docs are written, so every board reads the same way. Applies to board READMEs, board doc sites and this site.
Who we write for
Two readers, on every page:
- The newcomer — has soldered before, maybe flashed a Raspberry Pi, but has never brought up a bare Linux board. Needs the why, the steps in order, and every term explained once.
- The experienced builder — knows embedded Linux and wants facts fast: specs, pinouts, boot order, part guidance, known issues.
Serve both without making either wade through the other's material: lead with a short plain-language summary, then the details in tables. Explain a term the first time it appears on a page (or link the glossary); never assume it.
Voice
- Plain, direct, friendly. Second person ("you") for instructions; "we" for the project.
- Short sentences. One idea per sentence. Active voice ("Insert the card", not "The card should be inserted").
- Say what something does before what it is ("The debug console shows boot messages — it's the UART on header pins 11 and 12").
- Be honest about status: if something is untested, missing or broken, say so and link the issue. Don't call a board "stable" until a newcomer can follow the docs to a working board.
- No filler ("simply", "just", "easily", "obviously"). If it were simple, they wouldn't be reading.
Terms
Use one name per thing, everywhere:
| Use | Not |
|---|---|
| board | SBC (except in titles), module, device |
| cape | add-on, shield, HAT, expansion board |
| microSD card | SD, sd-card, card (alone, at first mention) |
| main header (J4) | expansion header, GPIO header |
| debug console | serial console, DBGU, UART0 (give the hardware name once in brackets) |
| USB-C port | microUSB, USB port |
| 3.3 V, 5 V (space, capital V) | 3v3, 3.3v, 5V |
| 64 MB, 2 Gbit | 64MB, 2Gb |
Spell out numbers with units consistently: 66 × 42 mm, 115200 baud, 1 A.
Page structure
Every page:
- Title — what the page is about, in words a newcomer would search for.
- One-paragraph summary — what you'll learn or do here, and who it's for.
- Body — for how-tos: numbered steps, each with the expected result. For reference: tables.
- What next / see also — links to the logical next page.
Use admonitions sparingly:
- !!! warning — can damage hardware or lose data.
- !!! note — limits and gotchas (e.g. "only cards up to 2 GB boot").
- !!! tip — optional shortcuts for experienced readers.
Board doc site layout
Every board site has the same sections, in this order:
| Section | Contents |
|---|---|
| Home | One sentence on what the board is; photo; links to Getting started and Build your own |
| Getting started | What you need, preparing the microSD card, first power-up, connecting the debug console, what you should see |
| Hardware → Overview | Specifications table; block diagram; what's on the board |
| Hardware → Connectors & pinout | Every connector with a pinout table: pin, signal, voltage, notes |
| Hardware → Power | Supply input, rails, current needs |
| Hardware → Boot & recovery | Boot order, media limits, recovery mode |
| Hardware → Schematics / PCB / BOM | Links to sources and outputs; stackup; BOM guidance |
| Hardware → Build your own | Fab requirements, assembly notes, difficulty |
| Hardware → Known issues | Open issues that affect users, with workarounds |
| Software | Boot chain overview; building from source |
| Journal | Board journal (dated entries) |
| Glossary | Link to the central glossary plus board-specific terms |
The README is a short version of Home + the specifications table + links into the site. It must not contradict the site.
Facts and sources
- Every number in the docs must match the hardware sources (KiCad files) or a cited datasheet. When the hardware changes, the docs change in the same pull request.
- Link datasheets from
resources/or by clean vendor URL (see references). - Mark unverified information as such ("not yet tested").