Parent epic: #246
A final quality gate over the written material — every .md file and every source
comment — before the first public release.
The audience is embedded engineers evaluating the library during procurement, so at
0.1.0 the documentation is part of the product rather than a support artifact. A
statement that is stale, contradicted elsewhere, or repeated in three places with
three different emphases costs the same as a defect, and is harder to find later
because nothing fails when it is wrong.
Axes
- Accuracy — does it describe what the code does now? Anything written ahead of
the implementation, or left behind by it.
- Duplication — one authoritative home per piece of knowledge. Where the same
rule is stated twice, one copy becomes a link.
- Repetition — the same point restated within a page, or a paragraph that adds
emphasis rather than information.
- Readability — plain declarative prose. Structure that lets a reader find the
answer without reading the whole page.
Scope
docs/** and the root .md files, including the community-health set.- Source comments in
Core/ and Platform/, and the @file briefs that generate
the API reference.
CLAUDE.md and SKILL.md — internal, but they are the contract this work is
judged against, and they are public in a public repo.
Source comments are deliberately in scope here rather than under E24, so the
audit is one ticket to iterate rather than two. E24 should not pick up a parallel
comment-quality story.
Method
Findings are collected as comments on this issue. Because the audit is about
consistency across the documentation set, a fix scoped to one page cannot be judged
against that standard — so work proceeds as commits on a single branch behind a draft
PR, which runs the docs gates continuously without spending a review on a partial
state. The PR is marked ready when the set is coherent, and that is when it is read.
The issue closes when the findings list is empty, not when the first PR merges.
Out of scope
Acceptance
- Every finding on the list is resolved, or explicitly declined with a recorded
reason.
markdownlint-cli2 clean, and the docs-build and analyze-markdown lanes green.- No statement in the audited set contradicts another, and each rule has one
authoritative home with links pointing at it.
Parent epic: #246
A final quality gate over the written material — every
.mdfile and every sourcecomment — before the first public release.
The audience is embedded engineers evaluating the library during procurement, so at
0.1.0 the documentation is part of the product rather than a support artifact. A
statement that is stale, contradicted elsewhere, or repeated in three places with
three different emphases costs the same as a defect, and is harder to find later
because nothing fails when it is wrong.
Axes
the implementation, or left behind by it.
rule is stated twice, one copy becomes a link.
emphasis rather than information.
answer without reading the whole page.
Scope
docs/**and the root.mdfiles, including the community-health set.Core/andPlatform/, and the@filebriefs that generatethe API reference.
CLAUDE.mdandSKILL.md— internal, but they are the contract this work isjudged against, and they are public in a public repo.
Source comments are deliberately in scope here rather than under E24, so the
audit is one ticket to iterate rather than two. E24 should not pick up a parallel
comment-quality story.
Method
Findings are collected as comments on this issue. Because the audit is about
consistency across the documentation set, a fix scoped to one page cannot be judged
against that standard — so work proceeds as commits on a single branch behind a draft
PR, which runs the docs gates continuously without spending a review on a partial
state. The PR is marked ready when the set is coherent, and that is when it is read.
The issue closes when the findings list is empty, not when the first PR merges.
Out of scope
CHANGELOG.md(generated by release-please) andLICENSE.md.docs/generated/**— regenerated, not authored.has not happened yet and are tracked there as part of cutting 0.1.0.
Acceptance
reason.
markdownlint-cli2clean, and thedocs-buildandanalyze-markdownlanes green.authoritative home with links pointing at it.