ADR-015: Human documentation is generated from artifacts, with provenance
Example from HELIX’s own docs. This generated page comes from
docs/helix/. Use it to see the method in practice; start with the artifact-type catalog for reusable templates. Historical plans and reports may describe retired architecture.
Source identity (from
02-design/adr/ADR-015-human-documentation-is-generated-from-artifacts-with-provenance.md):
ddx:
id: ADR-015
status: accepted
authoring:
home: repoADR-015: Human documentation is generated from artifacts, with provenance
Problem
HELIX artifacts are the system of record: dense, exact, and written in the artifact-signal voice for agents carrying context and reviewers tracing intent. Developers, operators, and users need answers in their own vocabulary, so projects either hand-write documentation beside the artifacts, which drifts from them silently, or rewrite the artifacts for readers, which costs the exactness agents and reviewers depend on. Either way nothing tells a project that its documentation has fallen behind the code it describes, and each repository solves it differently.
Decision
We will generate the pages people read from the artifacts and the code with the guide mode (FEAT-019, PRD R-13), record on each page the exact sources it was built from, and check those records on every change. HELIX owns the contract; the deterministic machinery is a host tool, documentor (tools/documentor/ in the HELIX repository), released with HELIX. Specifically:
- Catalog audiences (
workflows/publish/audiences/) define the pages each reader needs (developer, operator, user, data), with each page’s reader task, Diátaxis kind (tutorial, how-to, reference, explanation), outline, voice, budget, and source kinds. A project chooses audiences and adds, adopts, or delegates pages in.helix.ymlpublish:. The audience is ours; the kinds are Diátaxis’s, because that taxonomy already answers which page is missing and what a page must leave to another. - Every page starts with a provenance header naming each source, a path with an optional H2 section, and a digest of the text read (
workflows/references/publishing.md). - documentor’s check reports stale pages, missing sources, broken links and paths, unmapped watched files, handling breaches, and prose breaches, and fails the guide as a whole when a page is missing, stale, or unreviewed; it needs Python 3.11 and PyYAML, no agent and no network, so any project can gate CI on it, run from a HELIX release tag. Without documentor the agent performs the checks by hand and says so.
- documentor emits the pages into the site the repository already has (mkdocs or Hugo) and scaffolds a Hextra site only when it has none. The Markdown pages stay the record.
- Artifacts keep their voice and are never edited by
guide. A page follows the code where an artifact disagrees and reports the disagreement foralign. - The writing pass (
workflows/references/writing-pass.md) and the measured prose audit apply to published pages and deliverables, not to artifact types.
Why We Chose This
Over hand-written documentation beside the artifacts
A hand-written page has no record of what it was written from, so nothing can say when it goes wrong. Provenance with digests turns “the docs are out of date” from a reader’s complaint into a check that fails in the pull request that made them stale, naming the source that moved.
Over rewriting artifacts for human readers
Applying a readability standard to artifacts trades the exactness agents and reviewers rely on for a voice they do not need, and turns every governing document into a readability exercise. Projections keep each layer in its own voice: the record for agents, the page for people.
Over a documentation site as the source
A site is one renderer of the pages. Keeping Markdown pages as the record means GitHub renders them with no toolchain, the checks need only the standard library, and a project can adopt the site later or never.
Consequences
Good: Every HELIX project gets the same audiences, page shapes, checks, and site from one .helix.yml block, and HELIX itself stays content plus one skill: the stack-specific traits and generators live in documentor and in the adopting repositories. A change to a cited artifact section, configuration file, or code file fails the check until the page is regenerated, so documentation moves with the code. Diagrams come from a project’s architecture model, not from hand drawing.
Trade-offs: A page that cites a busy code file goes stale often; authors cite the files whose content the page states, not everything they read. The check needs documentor on the host or in CI; a repository that cannot install it keeps the by-hand path and no gate. Generation is agent work, so two regenerations of a page differ in wording; the checks, the flow outline, and the writing pass bound the difference.
Drift signals to watch: Pages edited by hand without a provenance header; headers stamped without the sources reread; artifacts edited from guide; a page that cites only artifacts and no code, so it can never go stale against the system it describes; machinery creeping back into the skill.
Concern Impact
- No concern impact: the decision adds a mode, catalog data, and scripts; it selects and overrides no concern.
Innsigle seal: model-primary by HELIX
The signature covers the markdown source of this page, not these HTML bytes. This page quotes that seal; verify it against the source file.
- Composition
- model-primary
- Issuer
- HELIX
helix - Signing key
ed25519:b0865d76d834a52c48506414d16f4e5a(build key)- Signed source
artifacts/adr/ADR-015-human-documentation-is-generated-from-artifacts-with-provenance.md- Signed
- 2026-11-16T15:52:45Z
- Content digest
sha256:eefbef96…95f99715
This build key is endorsed by the human key for build signing; the signature is not a detector and not a truth guarantee.
Raw attestation JSON
{
"payload": {
"innsigle": "1",
"type": "https://innsigle.dev/claim/colophon/v1",
"issued_at": "2026-11-16T15:52:45Z",
"issuer": {
"id": "helix",
"name": "HELIX",
"key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
"key_url": "https://documentdrivendx.github.io/helix/.well-known/innsigle/keys.json"
},
"subjects": [
{
"uri": "https://documentdrivendx.github.io/helix/artifacts/adr/ADR-015-human-documentation-is-generated-from-artifacts-with-provenance/",
"digest": {
"alg": "sha256",
"value": "eefbef969a9459ae77c9d63c373df8a0127d1e2561c97ec71cbb7be195f99715"
}
}
],
"colophon": {
"schema_version": "1",
"composition": "model-primary",
"ingredients": [
{
"kind": "model",
"name": "Claude",
"role": "draft"
},
{
"kind": "tool",
"name": "sloptimizer",
"role": "rewrite"
},
{
"kind": "human",
"name": "operator",
"role": "structure-edit"
}
],
"notes": null
}
},
"payload_encoding": "json",
"signatures": [
{
"key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
"alg": "ed25519",
"sig": "nqPkOWAAw3_2GSS2ZMsQoDgtGWEUzO_hsXoVSemd-2GzeXkd0LIoQcQFVsRyybkQq49t9UaRvFK1eMzuFrF1Aw",
"signed_at": "2026-11-16T15:52:45Z"
}
]
}