Documentation¶
How documentation is written, built and checked.
| Rule | Level | Applies to | Verified |
|---|---|---|---|
| KB-DOC-001 Markdown passes the org lint configuration | must | all | checked |
| KB-DOC-002 The documentation site builds strictly | must | driver, library, hal, tooling, docs, template | checked |
| KB-DOC-003 No broken links on the built site | must | driver, library, hal, tooling, docs, template | checked |
| KB-DOC-004 Every public API is documented and Doxygen is warning-free | must | driver, library, hal, template | checked |
| KB-DOC-005 Every public repository publishes a versioned MkDocs site | must | driver, library, hal, firmware, tooling, docs, template | checked |
| KB-DOC-006 Pages live in docs/ and the site config in _config/mkdocs.yml | must | driver, library, hal, firmware, tooling, docs, template | checked |
| KB-DOC-007 The navigation has the five standard tabs | must | driver, library, hal, firmware, tooling, docs, template | planned |
| KB-DOC-008 The site has the page set for its kind | must | driver, library, hal, firmware, tooling, template | planned |
| KB-DOC-009 Every code repository has a Contract page under Concepts | must | driver, library, hal, firmware, template | planned |
| KB-DOC-010 The Contract page has the standard sections in order | must | driver, library, hal, firmware, template | planned |
| KB-DOC-011 The Contract page lists every handbook rule the repository does not meet | must | driver, library, hal, firmware, template | review |
| KB-DOC-012 Repository docs link the handbook instead of restating it | should | all | review |
| KB-DOC-013 CONTRIBUTING.md links the handbook | should | all | review |
| KB-DOC-014 A change to behaviour or API updates its docs in the same pull request | should | all | planned |
| KB-DOC-015 The README has the standard sections in order | should | driver, library, hal, firmware, tooling, template | planned |
| KB-DOC-016 The README is short and leaves the reference to the site | should | all | planned |
| KB-DOC-017 A driver's README names the chip and the part, not the organisation | must | driver, template | planned |
| KB-DOC-018 The README licence line matches LICENSE and the package metadata | must | all | review |
| KB-DOC-019 A family driver is named after the member it was written for | should | driver | review |
| KB-DOC-020 Every C++ block on the site compiles | must | driver, library, hal, template | checked |
| KB-DOC-021 Examples check every result | must | driver, library, hal, firmware, template | checked |
| KB-DOC-022 Generated regions and figures match the code | must | driver, library, hal, firmware, template | planned |
| KB-DOC-023 The Porting page shows a complete, compiled port for each bus | must | driver, template | checked |
| KB-DOC-024 The API guide lists the errors each call can return | should | driver, template | review |
| KB-DOC-025 Every image has alt text | must | all | checked |
| KB-DOC-026 Figures are generated, themed, and drawn with the right tool | should | all | review |
| KB-DOC-027 A figure has one reading direction, verbs on its arrows and three tones at most | guide | all | none |
| KB-DOC-028 The site's changelog page includes CHANGELOG.md | must | driver, library, hal, firmware, tooling, template | review |
| KB-DOC-029 The changelog keeps [Unreleased] first and the standard subsections in order | must | all | planned |
| KB-DOC-030 A released changelog section is never edited | must | all | planned |
| KB-DOC-031 Changelog entries describe what a user sees | guide | all | none |
| KB-DOC-032 ADRs use the standard format and are numbered in acceptance order | must | all | planned |
| KB-DOC-033 An accepted decision is superseded, never rewritten | must | all | review |
| KB-DOC-034 Cross-repository decisions are handbook ADRs; local ones stay in the repository | should | all | review |
| KB-DOC-035 Datasheets are referenced by exact revision, never committed | must | driver, hal, template | checked |
| KB-DOC-036 Markdown wraps at 120 columns | must | all | checked |
| KB-DOC-037 Every page has one title, a purpose line and sections in reading order | should | all | checked |
| KB-DOC-038 Headings step one level at a time and code fences name their language | must | all | checked |
| KB-DOC-039 Links are relative, by file, with descriptive text | should | all | checked |
| KB-DOC-040 Documentation is Markdown | should | all | planned |
| KB-DOC-041 No Jekyll front matter or Liquid; front matter only for hide | must | all | checked |
| KB-DOC-042 Page file names are lower-case kebab-case | should | all | planned |
| KB-DOC-043 Write in the second person, present tense and active voice | should | all | planned |
| KB-DOC-044 No hype or filler words | should | all | planned |
| KB-DOC-045 No emoji, exclamation marks or walls of bold | should | all | planned |
| KB-DOC-046 Titles and headings are in sentence case | should | all | planned |
| KB-DOC-047 Pages never mention how they were produced | must | all | planned |
| KB-DOC-048 Spelling is correct and one variant is used per repository | should | all | planned |
| KB-DOC-049 Every name and number on a page is checked against its source | must | all | review |
| KB-DOC-050 Use a table for three or more like items, with units in the header | guide | all | none |
| KB-DOC-051 Use the theme's components instead of inventing markup | guide | all | none |
| KB-DOC-052 Guides teach a task with complete examples and say why | guide | all | none |
| KB-DOC-053 No undated future-plans sections | guide | all | none |
| KB-DOC-054 The site meets the Lighthouse accessibility budget | should | driver, library, hal, firmware, tooling, docs, template | planned |
| KB-DOC-055 Interrupt wiring is documented | should | driver, hal, template | review |
| KB-DOC-056 kb-core has one page per handler | must | library | review |
| KB-DOC-057 A utility collection has one guide page per utility | should | library | review |
| KB-DOC-058 A product documents its fault catalogue on the Operation page | must | firmware | review |
| KB-DOC-059 Release trains are announced with their bench status | should | library | review |
| KB-DOC-060 Patches to vendor-generated code are listed in PATCHES.md | should | hal | review |
| KB-DOC-061 The Doxyfile lives in _config/ and Doxygen runs from the root | must | driver, library, hal, template | planned |
| KB-DOC-062 Doxygen reads only the public headers and keeps private members out | must | driver, library, hal, template | planned |
| KB-DOC-063 A public function's comment gives units, errors and whether it blocks | must | driver, library, hal, template | checked |
| KB-DOC-064 Each test says what it verifies, with its data and expected result | should | driver, library, hal, firmware, template (safety level and above) | review |
| KB-DOC-065 A driver's docs trace each part of the driver to its datasheet section | must | driver, template | planned |
KB-DOC-001: Markdown passes the org lint configuration¶
MUST · all · since 1.0
Every Markdown file passes markdownlint-cli2 with the org configuration.
Verified by:
markdownlint/all(implemented): markdownlint-cli2 with the org config; the parameter names the rule (markdownlint/MD040)
KB-DOC-002: The documentation site builds strictly¶
MUST · driver, library, hal, tooling, docs, template · since 1.0
A repository with a documentation site builds it with mkdocs --strict: no broken internal link, no page left out of
the navigation.
Verified by:
mkdocs-strict(implemented): the documentation site builds with mkdocs --strict (no broken internal link, every page in the nav)
Explained in: standards/docs.md
KB-DOC-003: No broken links on the built site¶
MUST · driver, library, hal, tooling, docs, template · since 1.0
Every link on the built site resolves, internal and external.
Verified by:
link-check(implemented): lychee finds no broken link on the built site
KB-DOC-004: Every public API is documented and Doxygen is warning-free¶
MUST · driver, library, hal, template · since 1.0
Every public type, function and parameter in inc/ has a Doxygen comment; Doxygen runs with WARN_IF_UNDOCUMENTED =
YES and WARN_AS_ERROR = FAIL_ON_WARNINGS.
Verified by:
doxygen-warnings(implemented): Doxygen with WARN_AS_ERROR = FAIL_ON_WARNINGS and WARN_IF_UNDOCUMENTED reports nothing
Explained in: standards/docs.md
KB-DOC-005: Every public repository publishes a versioned MkDocs site¶
MUST · driver, library, hal, firmware, tooling, docs, template · since 1.0
Every public repository publishes its documentation at https://kokeb-labs.github.io/<repo>/ through
ru-mkdocs-publish, built with kokeb-mkdocs-theme and versioned per v* tag; a code repository merges its Doxygen
reference under api/. A -rc tag publishes its version without moving the latest alias.
Why: One platform and one theme mean a reader finds the same layout on every site, and a pinned version per tag means the page a user reads matches the code they built.
Verified by:
mkdocs-strict(implemented): the documentation site builds with mkdocs --strict (no broken internal link, every page in the nav)- review: The docs workflow calls ru-mkdocs-publish and the site is live at kokeb-labs.github.io/<repo>/.
Explained in: standards/docs.md
KB-DOC-006: Pages live in docs/ and the site config in _config/mkdocs.yml¶
MUST · driver, library, hal, firmware, tooling, docs, template · since 1.0
Pages live in docs/. The site configuration is _config/mkdocs.yml with docs_dir: ../docs, and the docs workflow is
passed mkdocs_config: _config/mkdocs.yml and, in a code repository, doxygen_config: _config/Doxyfile.
Verified by:
mkdocs-strict(implemented): the documentation site builds with mkdocs --strict (no broken internal link, every page in the nav)- review: The docs workflow passes mkdocs_config and doxygen_config with the _config/ paths.
See also: ADR-0011
Explained in: standards/docs.md
KB-DOC-007: The navigation has the five standard tabs¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · driver, library, hal, firmware, tooling, docs, template · since 1.0 · enforced from 2027-03-01
docs/.nav.yml has exactly five top-level tabs, in this order: Home, Get started, Concepts, Guides, Reference. Deep
dives go under Concepts and configuration references under Guides.
Verified by:
docs-nav(planned): docs/.nav.yml has exactly the five tabs Home, Get started, Concepts, Guides, Reference in order, and contract.md sits under Concepts right after Architecture
Explained in: standards/docs.md
KB-DOC-008: The site has the page set for its kind¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · driver, library, hal, firmware, tooling, template · since 1.0 · enforced from 2027-03-01
docs/ holds every page the documentation standard lists for the repository's kind (driver, standalone library,
kb-core, HAL, product, CI and tools). A page that cannot apply, such as Configuration for a driver with no Config, is
left out rather than kept empty.
Why: A fixed page set lets a reader move between repositories without relearning where things are, and lets a check say what is missing.
Verified by:
docs-page-set(planned): docs/ has every page the documentation standard requires for the repository's declared kind, and each is in the navigation
Explained in: standards/docs.md
KB-DOC-009: Every code repository has a Contract page under Concepts¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · driver, library, hal, firmware, template · since 1.0 · enforced from 2027-03-01
Every driver, library, kb-core, HAL and product has docs/contract.md, listed under Concepts right after Architecture.
Verified by:
docs-page-set(planned): docs/ has every page the documentation standard requires for the repository's declared kind, and each is in the navigationdocs-nav(planned): docs/.nav.yml has exactly the five tabs Home, Get started, Concepts, Guides, Reference in order, and contract.md sits under Concepts right after Architecture
Explained in: standards/docs.md
KB-DOC-010: The Contract page has the standard sections in order¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · driver, library, hal, firmware, template · since 1.0 · enforced from 2027-03-01
docs/contract.md has the sections Promises, Depends on, Threading, Errors, Memory, Platform and Deviations from the
standard, in that order, after a one-line purpose.
Why: The Contract is the short normative summary a caller or an auditor reads first; fixed sections make a missing promise visible.
Verified by:
heading-skeleton/contract(planned): a Markdown file's headings match a required skeleton in order (parameter: contract, readme, adr, hf-hal-readme, hf-board-spec, hf-protocol-spec)
See also: IEC 62304:2006+A1:2015 5.4.3 (detailed design of software unit interfaces)
Explained in: standards/docs.md
KB-DOC-011: The Contract page lists every handbook rule the repository does not meet¶
MUST · driver, library, hal, firmware, template · since 1.0
The Deviations section names, by rule ID, each handbook rule the repository does not meet yet, with its issue or waiver. An empty section says "None".
Verified by:
- review: Every waiver in .kokeb/handbook.yml and every known unmet rule appears in the Deviations section with its issue.
Explained in: deviations.md
KB-DOC-012: Repository docs link the handbook instead of restating it¶
SHOULD · all · since 1.0
The handbook is the single source of the rules. A repository's docs, Contract page, templates and CI link the rule they follow and state only what is specific to the repository; no repository keeps a copy of the handbook or of its pages.
Why: A copied rule drifts from the original the first time either is edited.
Verified by:
- review: No page restates a handbook rule that it could link; no vendored copy of handbook pages.
Explained in: standards/docs.md
KB-DOC-013: CONTRIBUTING.md links the handbook¶
SHOULD · all · since 1.0
A repository's CONTRIBUTING.md, or the organisation default it inherits, links the handbook. AGENTS.md links it as KB-AGT-005 requires.
Verified by:
- review: CONTRIBUTING.md (own or the org default) links kokeb-labs.github.io/handbook.
KB-DOC-014: A change to behaviour or API updates its docs in the same pull request¶
SHOULD · all · since 1.0
A pull request that changes behaviour, the public API, a pin, a default or a build option updates the README, the pages
under docs/ and the CHANGELOG entry that describe it, in the same pull request.
Why: Docs updated later are docs that are wrong in between, and usually stay wrong.
Verified by:
docs-touched(planned): warns when a pull request changes inc/, a Kconfig or a CMake option without touching README.md, docs/ or CHANGELOG.md- review: Every page that describes the changed behaviour is updated in this pull request.
KB-DOC-015: The README has the standard sections in order¶
Proposed
Warns until 2027-03-01, then fails CI.
SHOULD · driver, library, hal, firmware, tooling, template · since 1.0 · enforced from 2027-03-01
The README has, in order and only where they apply: title and hero line, true badges, the bold docs link, a plain-language paragraph, one figure, At a glance (with the status), Datasheet, Try it on your PC, Use it on your MCU, What it does, Install, Documentation (with "Read it when you want to"), Tests and quality, License.
Verified by:
heading-skeleton/readme(planned): a Markdown file's headings match a required skeleton in order (parameter: contract, readme, adr, hf-hal-readme, hf-board-spec, hf-protocol-spec)
Explained in: standards/docs.md
KB-DOC-016: The README is short and leaves the reference to the site¶
SHOULD · all · since 1.0
A README has no table of contents, no emoji walls, no check-mark feature lists, no badge that links nowhere or states something untrue, and no API tables that duplicate the site.
Verified by:
prose-style/emoji(planned): Vale with the Kokeb style; the parameter names the style rule- review: The README has none of the banned elements and every badge is live and true.
Explained in: standards/docs.md
KB-DOC-017: A driver's README names the chip and the part, not the organisation¶
MUST · driver, template · since 1.0
A driver's README and site name the chip and part it drives; the organisation appears only in links and the licence line, so the driver reads as usable on its own.
Verified by:
forbidden-patterns/readme-org-name(planned): a source scan for a construct the handbook bans; the parameter names the pattern set- review: The README names the chip and part; no Kokeb Labs or HardFOC branding outside links.
See also: ADR-0012
Explained in: standards/docs.md
KB-DOC-018: The README licence line matches LICENSE and the package metadata¶
MUST · all · since 1.0
The README's License line, LICENSE and every package manifest (idf_component.yml, library.json and the like) name
the same licence: MIT for code, CERN-OHL-P-2.0 for a hardware design.
Verified by:
- review: README License line, LICENSE and package manifests name the same licence.
See also: ADR-0009
KB-DOC-019: A family driver is named after the member it was written for¶
SHOULD · driver · since 1.0
A driver that covers a chip family is named after the part it was written and tested for; the README lists the other members it supports and how far each is tested.
Verified by:
- review: The repository name is the tested part; the README lists the other family members and their status.
Explained in: standards/driver.md
KB-DOC-020: Every C++ block on the site compiles¶
MUST · driver, library, hal, template · since 1.0
A C++ snippet longer than one line lives in tests/docs/*.cpp between --8<-- section markers, is built by the host
build with warnings on, and is included in the page; it is never pasted inline.
Why: An example that does not compile teaches the wrong API, and nobody notices until a user pastes it.
Verified by:
host-tests(implemented): the unit tests build and pass on the host with gcc and clangdocs-inline-code(planned): no C++ fence longer than one line in docs/ or README.md is written inline; each comes from tests/docs via a --8<-- include or a generated region
Explained in: standards/docs.md
KB-DOC-021: Examples check every result¶
MUST · driver, library, hal, firmware, template · since 1.0
Every example on the site and in the README checks each Result and Status it gets and shows what to do with an
error; no example ignores a return value or elides code with // ....
Verified by:
compiler-warnings/-Wunused-result(implemented): the build is warning-free with the named flag and -Werror- review: Each example handles every returned Result or Status.
Explained in: standards/docs.md
KB-DOC-022: Generated regions and figures match the code¶
Proposed
Warns until 2027-03-01, then fails CI. ru-mkdocs-publish runs the drift check today; once its job is named in the registry the check is implemented and this rule can be active.
MUST · driver, library, hal, firmware, template · since 1.0 · enforced from 2027-03-01
The README quickstart, examples lists and figures are generated regions (kokeb-docs), and CI fails when one no longer
matches the code it is generated from. kokeb-docs check runs the same check locally.
Verified by:
docs-drift(planned): kokeb-docs check finds no generated region (README quickstart, examples list) or figure that differs from what the code generates
Explained in: standards/docs.md
KB-DOC-023: The Porting page shows a complete, compiled port for each bus¶
MUST · driver, template · since 1.0
A driver's Porting page shows the full port for every bus it supports, compiled from tests/docs/, and lists every
extra protocol hook with the same contract as the core interface methods.
Verified by:
host-tests(implemented): the unit tests build and pass on the host with gcc and clang- review: Each supported bus has a compiled port on the Porting page; every extra hook is listed.
Explained in: standards/driver.md
KB-DOC-024: The API guide lists the errors each call can return¶
SHOULD · driver, template · since 1.0
A driver's API guide lists, for each call, the error values it can return and what each means, matching the @retval
lines in the headers.
Verified by:
- review: The API guide's error table matches the @return/@retval documentation in inc/.
Explained in: standards/driver.md
KB-DOC-025: Every image has alt text¶
MUST · all · since 1.0
Every image and figure has alt text: one sentence saying what it shows, never just "diagram" or "image".
Verified by:
markdownlint/MD045(implemented): markdownlint-cli2 with the org config; the parameter names the rule (markdownlint/MD040)- review: Alt text says what the figure shows.
Explained in: standards/docs.md
KB-DOC-026: Figures are generated, themed, and drawn with the right tool¶
SHOULD · all · since 1.0
Architecture and code-derived figures are figkit figures with light and dark variants; sequences and state machines are
Mermaid. A vendor image is an SVG or compressed PNG on a .kb-plate, never a screenshot of a PDF.
Verified by:
- review: New figures use figkit or Mermaid; vendor images are SVG/PNG with .kb-plate.
Explained in: standards/docs.md
KB-DOC-027: A figure has one reading direction, verbs on its arrows and three tones at most¶
GUIDE · all · since 1.0
A figure reads in one direction, stated in its subtitle; solid arrows call, dashed arrows carry data, and an arrow is labelled when its verb is not obvious. Colour shows ownership in at most three tones, with about eight cards at most.
KB-DOC-028: The site's changelog page includes CHANGELOG.md¶
MUST · driver, library, hal, firmware, tooling, template · since 1.0
docs/changelog.md has a title and purpose line and pulls in CHANGELOG.md with a snippet include; it never holds a
copy.
Verified by:
- review: docs/changelog.md uses --8<-- "CHANGELOG.md" and has no copied entries.
Explained in: standards/docs.md
KB-DOC-029: The changelog keeps [Unreleased] first and the standard subsections in order¶
Proposed
Warns until 2027-03-01, then fails CI. The planned changelog check must cover the [Unreleased]-first and subsection-order rules (Breaking is not a Keep a Changelog heading).
MUST · all · since 1.0 · enforced from 2027-03-01
## [Unreleased] is always the first section. Within a section the subsections are Breaking, Added, Changed,
Deprecated, Removed, Fixed and Security, in that order, each only when it has an entry.
Verified by:
changelog(planned): CHANGELOG.md follows Keep a Changelog; a new version section is the next SemVer step, dated, not empty
Explained in: standards/release.md
KB-DOC-030: A released changelog section is never edited¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · all · since 1.0 · enforced from 2027-03-01
A released section ## [X.Y.Z] - YYYY-MM-DD is not edited after its release, except for its link lines; a correction
goes in the next release's entry.
Verified by:
changelog-frozen(planned): a pull request's diff of CHANGELOG.md changes only the [Unreleased] section, a new release section and link lines
Explained in: standards/release.md
KB-DOC-031: Changelog entries describe what a user sees¶
GUIDE · all · since 1.0
A changelog entry says what changes for the user of the release (an API, a behaviour, a default, a fix to a symptom), not which commits went in.
Explained in: standards/release.md
KB-DOC-032: ADRs use the standard format and are numbered in acceptance order¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · all · since 1.0 · enforced from 2027-03-01
A decision record has a Status line and the sections Context, Decision and Consequences, and is numbered
NNNN-<slug>.md in the order decisions are accepted.
Verified by:
heading-skeleton/adr(planned): a Markdown file's headings match a required skeleton in order (parameter: contract, readme, adr, hf-hal-readme, hf-board-spec, hf-protocol-spec)
Explained in: standards/docs.md
KB-DOC-033: An accepted decision is superseded, never rewritten¶
MUST · all · since 1.0
Once an ADR is accepted its Decision is not edited to change it; a new ADR supersedes it, and the old one's Status links its successor.
Why: The record is only useful if it shows what was decided at the time, and why.
Verified by:
- review: A pull request that edits an accepted ADR changes only its Status, links or typos.
Explained in: standards/docs.md
KB-DOC-034: Cross-repository decisions are handbook ADRs; local ones stay in the repository¶
SHOULD · all · since 1.0
A decision that affects more than one repository is an ADR in the handbook's docs/adr/. A decision local to one
repository, including a product's, is an ADR in its own docs/adr/ in the same format.
Verified by:
- review: A new ADR is in the handbook when it binds other repositories.
Explained in: standards/docs.md
KB-DOC-035: Datasheets are referenced by exact revision, never committed¶
MUST · driver, hal, template · since 1.0
No datasheet, reference manual or application note is committed. docs/datasheets.yml lists each document the code was
written against: vendor, title, document number, revision, date, URL and the SHA-256 of the PDF that was used.
Verified by:
tracked-files/datasheets(implemented): git tracks no file of a banned kind; the parameter names it (tracked-files/symlinks, tracked-files/sdkconfig, tracked-files/idf-component)- review: docs/datasheets.yml names the document number, revision and SHA-256 of every datasheet the code cites.
See also: ADR-0019
KB-DOC-036: Markdown wraps at 120 columns¶
MUST · all · since 1.0
Prose lines in Markdown are at most 120 characters; tables and code blocks are exempt.
Verified by:
markdownlint/MD013(implemented): markdownlint-cli2 with the org config; the parameter names the rule (markdownlint/MD040)
Explained in: standards/naming-and-style.md
KB-DOC-037: Every page has one title, a purpose line and sections in reading order¶
Proposed
Warns until 2027-03-01, then fails CI. config/.markdownlint.json must enable MD025 and MD041 (MD041 with front matter
allowed, for hide:).
SHOULD · all · since 1.0 · enforced from 2027-03-01
A page starts with exactly one # title matching its navigation entry, then a one-sentence purpose line, then ##
sections in the order a reader needs them, ending with a next step when there is an obvious one.
Verified by:
markdownlint/MD025(implemented): markdownlint-cli2 with the org config; the parameter names the rule (markdownlint/MD040)markdownlint/MD041(implemented): markdownlint-cli2 with the org config; the parameter names the rule (markdownlint/MD040)- review: The page has a purpose line under its title.
KB-DOC-038: Headings step one level at a time and code fences name their language¶
Proposed
Warns until 2027-03-01, then fails CI. config/.markdownlint.json must enable MD040.
MUST · all · since 1.0 · enforced from 2027-03-01
Heading levels go down one at a time and use # style throughout. Every fenced code block names its language (cpp,
yaml, mermaid, text).
Verified by:
markdownlint/MD001(implemented): markdownlint-cli2 with the org config; the parameter names the rule (markdownlint/MD040)markdownlint/MD003(implemented): markdownlint-cli2 with the org config; the parameter names the rule (markdownlint/MD040)markdownlint/MD040(implemented): markdownlint-cli2 with the org config; the parameter names the rule (markdownlint/MD040)
KB-DOC-039: Links are relative, by file, with descriptive text¶
SHOULD · all · since 1.0
Pages link other pages by file (porting.md#threads), repository files relatively, and the API reference by
api/...html; no page links its own site or repository by absolute URL. Link text says where it goes, and external
links go to the primary source.
Verified by:
markdownlint/MD059(implemented): markdownlint-cli2 with the org config; the parameter names the rule (markdownlint/MD040)forbidden-patterns/absolute-self-links(planned): a source scan for a construct the handbook bans; the parameter names the pattern set- review: External links point at the primary source (vendor, datasheet, specification).
Explained in: standards/docs.md
KB-DOC-040: Documentation is Markdown¶
Proposed
Warns until 2027-03-01, then fails CI.
SHOULD · all · since 1.0 · enforced from 2027-03-01
Documentation is written in Markdown in the repository; no Word, PDF or slide files stand in for pages. Vendor datasheets (KB-DOC-035) are the only exception.
Verified by:
forbidden-patterns/office-docs(planned): a source scan for a construct the handbook bans; the parameter names the pattern set
KB-DOC-041: No Jekyll front matter or Liquid; front matter only for hide¶
MUST · all · since 1.0
Pages have no Jekyll front matter and no Liquid tags. Material front matter is used only for hide:, for example on the
home page.
Verified by:
mkdocs-strict(implemented): the documentation site builds with mkdocs --strict (no broken internal link, every page in the nav)
Explained in: standards/docs.md
KB-DOC-042: Page file names are lower-case kebab-case¶
Proposed
Warns until 2027-03-01, then fails CI.
SHOULD · all · since 1.0 · enforced from 2027-03-01
Files under docs/ are named in lower-case kebab-case (api-guide.md, contract.md). The conventional root files
(README.md, CHANGELOG.md, CONTRIBUTING.md, AGENTS.md, CLAUDE.md, LICENSE) keep their upper-case names.
Verified by:
doc-file-names(planned): every file under docs/ is lower-case kebab-case; root README, CHANGELOG, CONTRIBUTING, AGENTS, CLAUDE and LICENSE are exempt
KB-DOC-043: Write in the second person, present tense and active voice¶
Proposed
Warns until 2027-03-01, then fails CI. The Vale rules report at warning level for passive voice.
SHOULD · all · since 1.0 · enforced from 2027-03-01
Pages address the reader as "you", in the present tense and active voice, in short sentences of one idea each. A page does not describe itself ("this document describes").
Verified by:
prose-style/passive-voice(planned): Vale with the Kokeb style; the parameter names the style ruleprose-style/future-tense(planned): Vale with the Kokeb style; the parameter names the style ruleprose-style/self-reference(planned): Vale with the Kokeb style; the parameter names the style rule
Explained in: standards/docs.md
KB-DOC-044: No hype or filler words¶
Proposed
Warns until 2027-03-01, then fails CI.
SHOULD · all · since 1.0 · enforced from 2027-03-01
Pages are plain and specific: numbers, names and units instead of "simply", "just", "easily", "powerful", "comprehensive", "seamless" or "robust".
Verified by:
prose-style/hype-words(planned): Vale with the Kokeb style; the parameter names the style rule
KB-DOC-045: No emoji, exclamation marks or walls of bold¶
Proposed
Warns until 2027-03-01, then fails CI.
SHOULD · all · since 1.0 · enforced from 2027-03-01
Headings, lists and tables carry no emoji; prose has no exclamation marks and no runs of bold text.
Verified by:
prose-style/emoji(planned): Vale with the Kokeb style; the parameter names the style ruleprose-style/exclamation(planned): Vale with the Kokeb style; the parameter names the style rule
KB-DOC-046: Titles and headings are in sentence case¶
Proposed
Warns until 2027-03-01, then fails CI.
SHOULD · all · since 1.0 · enforced from 2027-03-01
Every title and heading, the page title included, is in sentence case ("Bus settings").
Verified by:
prose-style/sentence-case(planned): Vale with the Kokeb style; the parameter names the style rule
KB-DOC-047: Pages never mention how they were produced¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · all · since 1.0 · enforced from 2027-03-01
No page says it was generated or written by a tool or an assistant, and no page names one as its author. Generated-region markers are comments, not prose.
Verified by:
prose-style/provenance(planned): Vale with the Kokeb style; the parameter names the style rule
KB-DOC-048: Spelling is correct and one variant is used per repository¶
Proposed
Warns until 2027-03-01, then fails CI.
SHOULD · all · since 1.0 · enforced from 2027-03-01
Pages have no misspellings, and a repository uses British or American spelling consistently; project words are listed in
config/typos.toml.
Verified by:
spelling(planned): typos finds no misspelling (project words in config/typos.toml)prose-style/spelling-variant(planned): Vale with the Kokeb style; the parameter names the style rule
KB-DOC-049: Every name and number on a page is checked against its source¶
MUST · all · since 1.0
Every API name, signature, pin, register and number is checked against the headers or the datasheet. A timing or performance figure is measured, with its conditions, or says that it is derived.
Why: A plausible wrong number costs a user more than a missing one.
Verified by:
- review: Numbers and names on changed pages match the headers or datasheet; derived figures say so.
KB-DOC-050: Use a table for three or more like items, with units in the header¶
GUIDE · all · since 1.0
Pins, registers, parameters, options, commands and error codes go in a table once there are three or more, with units in
the header (Range (V)), names in code font and long prose below the table.
KB-DOC-051: Use the theme's components instead of inventing markup¶
GUIDE · all · since 1.0
Admonitions, tabs, chip cards, steps and API links use the theme's components. A page has at most two warning or
danger admonitions, kept for damage or lost hours.
KB-DOC-052: Guides teach a task with complete examples and say why¶
GUIDE · all · since 1.0
A guide page is organised by task, gives the smallest complete example for each step, and says why a step is needed as well as how.
KB-DOC-053: No undated future-plans sections¶
GUIDE · all · since 1.0
Pages describe what exists. Plans go in issues or discussions, not in "future work" or "roadmap" sections of the docs.
KB-DOC-054: The site meets the Lighthouse accessibility budget¶
Proposed
Warns until 2027-03-01, then fails CI.
SHOULD · driver, library, hal, firmware, tooling, docs, template · since 1.0 · enforced from 2027-03-01
The built site scores at or above the org Lighthouse budget for accessibility, performance, best practices and SEO.
Verified by:
lighthouse(planned): Lighthouse scores of the built site meet the org budget for accessibility, performance, best practices and SEO (ru-mkdocs-publish runs Lighthouse; register it as implemented once its failing job is confirmed)
KB-DOC-055: Interrupt wiring is documented¶
SHOULD · driver, hal, template · since 1.0
When a driver or HAL needs an interrupt, its docs say which callback or vector handler the user wires, which context it runs in, and what it may call.
Verified by:
- review: The Porting or Contract page names the ISR hook, its context and what it may call.
KB-DOC-056: kb-core has one page per handler¶
MUST · library · since 1.0
kb-core documents each handler on its own page under docs/handlers/, with its API, error mapping, locking and
diagnostics.
Verified by:
- review: Every handlers/<chip> folder has a docs/handlers/ page with the four sections.
Explained in: standards/handler.md
KB-DOC-057: A utility collection has one guide page per utility¶
SHOULD · library · since 1.0
A library that is a collection of utilities has one guide page per utility, with its purpose, a compiled example and its complexity and memory use.
Verified by:
- review: Each public utility header has a guide page with purpose, example, complexity and memory.
Explained in: standards/library.md
KB-DOC-058: A product documents its fault catalogue on the Operation page¶
MUST · firmware · since 1.0
A product keeps one fault catalogue (ID, protocol code, severity, reaction) and documents it on its Operation page.
Verified by:
- review: The Operation page lists every fault in the catalogue with its code, severity and reaction.
Explained in: standards/product.md
KB-DOC-059: Release trains are announced with their bench status¶
SHOULD · library · since 1.0
A kb-core release train is announced in its release notes and on the Release trains page, with the bench status of each member.
Verified by:
- review: The release notes and Release trains page list the train's members and bench status.
Explained in: standards/release.md
KB-DOC-060: Patches to vendor-generated code are listed in PATCHES.md¶
SHOULD · hal · since 1.0
Any edit to vendor-generated code (STM32Cube and the like) after generation is listed in PATCHES.md beside it, with
why; the aim is none.
Verified by:
- review: A diff against the regenerated output matches what PATCHES.md lists.
KB-DOC-061: The Doxyfile lives in _config/ and Doxygen runs from the root¶
MUST · driver, library, hal, template · since 1.0
Each code repository keeps its Doxyfile at _config/Doxyfile, derived from the shared settings in ci-tools, and runs
doxygen _config/Doxyfile from the repository root so its paths are root-relative.
Verified by:
doxyfile-baseline(planned): _config/Doxyfile exists and sets INPUT to the public headers, EXTRACT_ALL and EXTRACT_PRIVATE to NO, WARN_NO_PARAMDOC to YES and the org mainpage, compared with the ci-tools baseline- review: _config/Doxyfile exists and its paths are relative to the root.
See also: ADR-0011
Explained in: standards/docs.md
KB-DOC-062: Doxygen reads only the public headers and keeps private members out¶
Proposed
Warns until 2027-03-01, then fails CI. driver-template matches; ci-tools' shared Doxyfile uses INPUT = README.md ... with RECURSIVE = YES and must be brought in line.
MUST · driver, library, hal, template · since 1.0 · enforced from 2027-03-01
The Doxyfile sets INPUT to the public headers only (inc/ for a driver), EXTRACT_ALL = NO, EXTRACT_PRIVATE = NO,
WARN_NO_PARAMDOC = YES, USE_MDFILE_AS_MAINPAGE = docs/_doxygen/mainpage.md, and generates HTML that is merged into
the site under api/.
Why: With EXTRACT_ALL off, an undocumented symbol is a warning instead of an empty entry, so KB-DOC-004 can fail on it.
Verified by:
doxyfile-baseline(planned): _config/Doxyfile exists and sets INPUT to the public headers, EXTRACT_ALL and EXTRACT_PRIVATE to NO, WARN_NO_PARAMDOC to YES and the org mainpage, compared with the ci-tools baseline
Explained in: standards/docs.md
KB-DOC-063: A public function's comment gives units, errors and whether it blocks¶
MUST · driver, library, hal, template · since 1.0
Each public symbol has a brief description. Each public function documents every parameter with its unit, its return value and the error values it can return, and whether it does I/O or blocks.
Verified by:
doxygen-warnings(implemented): Doxygen with WARN_AS_ERROR = FAIL_ON_WARNINGS and WARN_IF_UNDOCUMENTED reports nothing- review: Changed public functions document units, error values and whether they do I/O or block.
See also: IEC 62304:2006+A1:2015 5.4.2 (detailed design of each software unit)
Explained in: standards/docs.md
KB-DOC-064: Each test says what it verifies, with its data and expected result¶
SHOULD · driver, library, hal, firmware, template (safety level and above) · since 1.0
At safety level each test case has a Doxygen comment naming the requirement or behaviour it verifies, the input data and the expected result.
Why: The comment is the trace from a requirement to its test that an assessor reads.
Verified by:
- review: Each new or changed test has a comment naming what it verifies, its data and expected result.
KB-DOC-065: A driver's docs trace each part of the driver to its datasheet section¶
MUST · driver, template · since 1.0
docs/datasheets.yml lists, besides the documents, one topic per thing the driver takes from them: the datasheet's
section and printed page, the driver API and the docs pages that explain it. The README and home page carry the
generated datasheet card, docs/datasheet.md the generated map, and each page a topic names the generated box of the
sections it relies on.
Why: A reader, a reviewer or an assessor can check any behaviour against the source document in one step, and a new datasheet revision shows exactly which parts of the driver to re-check.
Verified by:
docs-drift(planned): kokeb-docs check finds no generated region (README quickstart, examples list) or figure that differs from what the code generates- review: Each topic names the right section and page; every docs page that rests on the datasheet has its box.
See also: ADR-0019
Explained in: standards/docs.md