Skip to content

Documentation style guide

What every Kokeb Labs documentation site contains, how its pages are written and what a README looks like. The pilot site, kokeb-labs/driver-tmc9660, follows every rule here; copy its structure.

Voice

  • Plain and specific. "SPI mode 3, up to 10 MHz", not "supports high-speed SPI". Numbers, names, units.
  • Second person, present tense, active voice. "Call init() before anything else", not "The init function should be called".
  • Short sentences. One idea each. A paragraph is three to five sentences.
  • No hype, no filler. No "simply", "just", "easily", "powerful", "comprehensive", "seamless", "robust".
  • No emoji in headings, lists or tables. No walls of bold. No exclamation marks.
  • Sentence case for titles and headings: "Bus settings", not "Bus Settings".
  • British or American spelling: either, consistently within a repository.
  • True statements only. Every API name, signature, pin, register and number is checked against the headers or the datasheet. When something is derived rather than measured, say so.
  • Never mention how the page was produced. No "generated by", no tool or assistant names.

Every page

  1. A title (# Title, level one, exactly one), matching its navigation entry.
  2. A purpose line right under it: one sentence saying what the reader gets from the page. The theme renders it as the lead paragraph.
  3. Sections (##) in the order a reader needs them. A section that is only a link list belongs in a table or in the navigation instead.
  4. A next step when there is an obvious one (Next: [Porting](porting.md)).

No Jekyll front matter, no Liquid. Material front matter is allowed only for hide: (the home page hides the navigation and table of contents).

Components

The theme styles these; use them instead of inventing markup.

Need Write Notes
A warning that prevents damage or lost hours !!! warning "Title" / !!! danger At most two per page. note, tip, example for the rest
Optional detail ??? note "Title" Collapsed by default
Alternatives (SPI / UART, ESP-IDF / CMake) === "SPI" tabs Same structure in each tab
Code fenced block with a language; title="file.cpp" for a file Code from a compiled file: --8<-- "tests/docs/x.cpp:section"
Registers, parameters, pins, options a table Header row, units in the header, code font for names
Bit fields a table inside <div class="kb-registers" markdown> Offset and name columns get code font
Sequence or state machine a mermaid fence Themed for light and dark automatically
Architecture, signal flow, layouts a figkit figure Light and dark from one layout, checked for contrast
A light-only image (vendor SVG, photo) ![alt](x.svg){ .kb-plate } Sits on a white plate in dark mode
Steps <div class="kb-steps" markdown> around an ordered list Numbered circles and a rail
The chip or board summary the chip card (below) Home page of a driver or HAL
A short label <span class="kb-badge">SPI</span> Tones: kb-badge--teal, --amber, --rose
A link into Doxygen [Class::method](api/....html){ .kb-api } From api-reference.md, or any page
Landing hero <div class="kb-hero" markdown> with kb-kicker, # Title, a paragraph, buttons Home page only
Navigation cards <div class="grid cards" markdown> Home page; four to six cards

Chip card

<div class="kb-chip" markdown>
<div class="kb-chip__head">
<span class="kb-chip__kicker">Smart gate driver with on-chip FOC</span>
<span class="kb-chip__name">TMC9660</span>
<span class="kb-chip__vendor">Analog Devices (Trinamic)</span>
</div>

Interface
:   SPI mode 3 up to 10 MHz, or UART

Supply
:   7.7 V to 70 V

[Datasheet](datasheet/tmc9660.pdf) ยท [Reference manual](datasheet/ref.pdf)
</div>

Five to seven rows: function, interface (mode, speed, address), supply, key limits, package, and the mode the driver uses. A board uses class="kb-chip kb-chip--board" with MCU, power input, connectors, chips on board.

Code

  • It compiles against the real API. In a C++ repository, every snippet longer than one line lives in build (an OBJECT library, warnings on) and is included in the page with --8<-- "tests/docs/x.cpp:name". Instantiate the driver template over the documented port so the whole API is compiled.
  • It is the smallest complete thing. Includes, the object, the calls, the error check. No // ... in a block that claims to be complete.
  • It checks results. Every driver call returns a status: show what to do with it.
  • Names are real. A reader can paste them. One-line inline names (setTargetVelocityRpm()) are checked by searching the headers.
  • The README quickstart is a generated region (<!-- generated: quickstart-code -->) copied from the same compiled file, so it cannot drift.

Figures

  • figkit for architecture and anything drawn from the code: one module per figure in docs/diagrams/figures/<id>.py, data() reads the facts from the headers, build() lays out cards. The build refuses text under 4.5:1 contrast in either theme, overlaps and missing alt text; kokeb-docs figures --check fails CI when the code changed and the figure did not. Embed with <!-- figure: <id> --> / <!-- /figure -->.
  • Mermaid for sequences and state machines.
  • Chip figures (pinout, block diagram, application circuit) are not written as modules: they are drawn from docs/hardware.yml (Chip hardware).

Chip hardware

Every driver describes its chip once, in docs/hardware.yml (Chip diagrams), and its Hardware page shows, in this order:

  1. The pinout (<!-- figure: chip-pinout -->): the package from the top, pins on the sides and in the order of the datasheet, pin 1 marked, coloured by electrical type, each pin's port hook beside it.
  2. The pin table (<!-- generated: chip-pins -->): pin, name, type and domain, function, driver hook, what to do when unused, datasheet section and page. No hand-written pin table next to it.
  3. The block diagram (<!-- figure: chip-blocks -->), from the datasheet's own, with the pins that reach each block.
  4. The application circuit (<!-- figure: chip-circuit-<id> -->) and its parts (<!-- generated: chip-parts -->): MCU, supplies, decoupling, pull-ups, loads and sense resistors as schematic symbols, every MCU wire labelled with the hook that drives it (GpioSet(CtrlPin::Reset)). A second circuit (the minimal wiring, a variant) is a second entry under circuits.

The README shows the same chip at a glance, under "At a glance": <!-- figure: chip-pinout -->, <!-- figure: chip-outline --> (the to-scale package body, from package.outline) and <!-- figure: chip-blocks -->, then the <!-- generated: chip-card --> table (package, pins, body size, pitch, supply, other packages), all from the same file.

Every fact cites the datasheet section and printed page. A value the datasheet does not give (a pull-up chosen by the application, an example load) carries unverified with the reason, and the page shows it as such. The reference circuit can be exported for a board design with kokeb-docs hardware --kicad-netlist.

How a figure reads

Most confusing diagrams mix up what an arrow means or which way to read. Every figure follows these rules:

  • One reading direction, said in the subtitle. Top to bottom for layers and calls, left to right for steps in time. When two things happen at different times (a push and a tag), draw two lanes, one per trigger, each with its trigger as the lane title.
  • Every arrow is a verb. Solid arrows run or call something; dashed arrows carry data (a file, an artifact, a setting). Label an arrow whenever the verb isn't obvious from the legend (uploads, reads, forwards to your hooks). An arrow points from the one acting to the one acted on.
  • Colour is ownership, three tones at most. teal is what the reader writes or owns, brand is this repository, slate is outside (hardware, GitHub, ESP-IDF). Draw owned cards with accent=True so they match the legend swatches. Add ("~solid", ...) and ("~dashed", ...) to the legend when both arrow kinds appear.
  • Few boxes, short text. At most about eight cards, a title and one or two short lines each. Lists that come from the code (public calls, commands) go in chips inside a region.
  • Say the point. The subtitle states the one thing the reader should take away; a note answers the question the figure raises (for example, why the release does not rebuild).
  • Vendor diagrams only as SVG or compressed PNG, with { .kb-plate }, never screenshots of PDFs.
  • Alt text on every image: one sentence that says what the figure shows, not "diagram". The build fails on a missing alt.
  • PDFs (datasheets, manuals) live in docs/datasheet/ and are linked, never embedded; the site links them on GitHub, which renders them.

Tables

Use a table whenever there are three or more items with the same attributes: pins, registers, parameters, options, commands, error codes, compile-time switches. Put units in the header (Range (V)), names in code font, and keep cells short; long prose goes under the table.

  • Link pages by file ([Porting](porting.md#threads)); MkDocs checks them in strict mode.
  • Link repository files relatively ([`inc/x.hpp`](../inc/x.hpp)); the plugin turns them into GitHub links at the commit that was built.
  • Link the API reference with api/...html; the link check verifies it after Doxygen is merged.
  • External links go to the primary source (vendor page, datasheet, specification).

Standard page sets

Driver (driver-*)

Page File Contains
Home index.md Hero (what, one-sentence why, buttons), the "no platform code" paragraph, chip card, "What you get" (5-7 bullets, each linking its page), navigation cards
Quickstart quickstart.md Safety note if it moves hardware; wiring table; add the driver; the port (compiled); a ~15-line example (compiled); what each step does; a "if it does not work" table
Installation installation.md Requirements; submodule; CMake target and options; ESP-IDF component; build layout; version; compile-time switches
Hardware hardware.md The chip figures and the pin table from docs/hardware.yml (below): pinout, generated pin table, block diagram, application circuit and its parts; control pins; bus settings table (mode, speed, frame, timing); a timing diagram or Mermaid sequence for the protocol; power ranges; errata that affect the host; evaluation boards; reference documents table
Architecture architecture.md The layer figure (core, communication interface, platform port); a table of layers with files; one call traced through the layers (Mermaid); design choices (CRTP, no heap); source map
API guide api-guide.md Task-oriented, compiled snippets: the shape of the API (subsystems table); initialise; configure; read; write; batch or stream if any; raw register / parameter access; errors and faults (a table of signals); tuning
API reference api-reference.md Button to api/index.html; a "start here" table of the five most useful Doxygen pages
Examples examples.md <!-- generated: examples --> (from examples/*/app_config.yml); one-time setup; "what to read in an example" table
Porting porting.md The interface methods table with contracts; the port for each bus (compiled); rules for the transfer; control-pin levels; reference implementation; how to check a port; threads
Testing and CI testing.md Host tests (how to run, what each file covers); compiled snippets; CI workflows table; hardware tests
Troubleshooting troubleshooting.md Symptom, cause, fix; start with the cheapest check
Changelog changelog.md # Changelog, a purpose line and --8<-- "CHANGELOG.md:N" (from the line after the file's own title)
Figures diagrams/index.md Written by kokeb-docs figures

Deep-dive pages (bootloader, protocols, timing, units, calibration) go under Concepts; configuration references under Guides. Navigation (docs/.nav.yml) is always five tabs:

nav:
  - Home: index.md
  - Get started: [Quickstart, Installation, Hardware]
  - Concepts: [Architecture, deep dives ...]
  - Guides: [API guide, Configuration, Porting, Examples, Troubleshooting]
  - Reference: [API reference, Testing and CI, Figures, Changelog]

Core library (kb-core)

Home (hero, what problem it solves, a feature list, a "used by" table), Quickstart (smallest use), Concepts (the model the library implements, with a figure), API guide (by task), API reference, Integration (CMake / ESP-IDF, configuration macros), Testing and CI, Changelog. A utilities collection gets one page per utility under Guides, each with purpose, a compiled example and complexity or memory notes.

Board support (HAL) repositories

Home with a board card (kb-chip kb-chip--board): MCU, power, connectors, chips on board; Quickstart (flash an example, see output); Hardware (block diagram figure, pin map as a generated table from the pin configuration, connectors, power tree); Architecture (managers, how drivers are wired, figure); one guide page per board function; API reference; Examples; Bring-up and troubleshooting; Changelog.

Firmware products

Home (what the product does, a photo or render with alt text, status), Getting started (flash, connect, first run), Architecture (tasks, data flow, figures), Operation (modes, commands, configuration), Hardware (link the HAL site), Development (build, test, release), Troubleshooting, Changelog. Decisions as ADRs under Reference.

CI and tool repositories (ci-tools, espidf-tools)

Home (what it provides, a table of workflows or scripts), Quickstart (the smallest caller), one page per workflow or script (purpose, jobs and permissions, inputs table generated from the YAML, example caller, failure modes), Versioning, Migration guides, Changelog.

Organisation (.github, kokeb-labs.github.io)

The portal (kokeb-labs.github.io) is the org home: what Kokeb Labs is, a card per product and HAL, a table of every driver with its chip, bus and docs link, and contribution links. .github holds the profile README following the README standard, plus community files.

README standard

The README is the front door on GitHub. It is short and points to the site.

  1. # Name and a hero line: one sentence, what it is and what it does.
  2. Badges that are true, in this order, only those that exist: CI (the main test workflow, branch=main), docs (the docs workflow, linking the site), license, latest release (only once a release exists). No coverage badge without coverage, no "PRs welcome", no badge for a language version.
  3. The documentation link in bold.
  4. One diagram: the layer or block figure (figkit marker).
  5. A 30-second example: the generated quickstart region.
  6. What it does: five to seven bullets.
  7. Install: the submodule line and the CMake lines.
  8. Documentation: a table of the five or six most useful pages, linked to the site (/latest/...).
  9. Tests: one command line.
  10. License: one line.

No table of contents, no walls of emoji, no feature lists with check marks, no badges that link nowhere, no duplicated API tables (that is the site's job).

Checks that enforce this

Check Where Fails on
mkdocs build --strict PR CI broken links and anchors, pages missing from the nav, no H1, Jekyll front matter, Liquid, a page colliding with api/, an image without alt text or file
kokeb-docs check PR CI an invalid docs/hardware.yml; a figure or generated region that no longer matches the code
Host build of tests/docs/ PR CI (repository) a snippet that does not compile
lychee offline PR CI a broken link or anchor in the built site, API included
Lighthouse PR CI performance, accessibility, best practices or SEO under budget
markdownlint PR CI (repository) Markdown style