Documentation Standards

Treat documentation as a first-class part of the codebase.

Keep docs:

• Useful: answer a concrete question someone will have.
• Non-redundant: one place per concept.
• Stable: describe contracts and workflows, not incidental details.
• Small: minimal surface area to reduce drift and improve maintainability.
• Concise: get to the point quickly without unnecessary exposition.
• Purposeful: avoid “docs for docs’ sake,” especially where code is the source of truth.
• Correct: avoid drift and outdated information; revisit and update regularly.

Aim for clean, maintainable docs with the same design quality as the code.

Docs Layout

• Home (docs/index.md): landing page and top-level product positioning.
• Guide (docs/guide/): user onboarding and usage flows.
• Reference (docs/reference/): external contracts, generated references, manifests, and per-rule reference pages.
• Developer (docs/developer/): contributor architecture, standards, policies, and operational workflows.
• ADRs (docs/adr/) - repo-only: enduring architecture decisions kept in the repository but excluded from the published docs site.
• Design docs (docs/design/) - ephemeral: design rationale and exploration.
• Plan docs (docs/plans/) - ephemeral: implementation plans and rollout specs.
• Static assets (docs/public/): files served directly by the docs site.
• Site infrastructure (docs/.vitepress/): VitePress config, theme code, and generated navigation artifacts.

Design and plan docs are temporary artifacts. ADRs are durable but repo-only artifacts. As work lands, fold the durable public-facing parts into docs/developer or docs/reference and keep ADRs as repository history rather than publishing them in public facing docs.

Rules For Enduring Developer Docs

Prefer one reference doc per topic

• Choose one document to be the reference for a topic.
• Other docs should link to it rather than re-explaining it.
• Refactors and consolidations are encouraged.

Respect generated doc boundaries

• If a file is generated by tq-docsgen, change the source manifest or generator code and regenerate.
• Keep generator inputs adjacent to the reference surface they feed.
• Do not hand-edit generated navigation or reference output unless ownership has intentionally moved.

Document contracts, not implementation trivia

Avoid:

• Specific issue/PR numbers.
• Temporary sprint plans or “current state” snapshots (keep in docs/design).
• Enumerations of internal event names unless they are a public contract.
• File-by-file code tours when an architecture or workflow doc would be more stable.

Keep examples minimal and durable

• Use the smallest example that demonstrates the feature.
• Prefer examples that avoid internal-only types.
• When possible, prefer examples that are unlikely to change.

Doc Quality Standards

Avoid these anti-patterns

• Duplicate explanations: same topic described in multiple places.
• Leaky layering: docs exposing internal implementation details.
• Brittle examples: examples tied to unstable internal structures.
• Generated-file edits: fixing generated output by hand instead of updating its source.
• Navigation drift: adding pages without wiring them into the section that owns them.
• Over-documentation: documenting obvious code-level details.