tq

Appearance

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.
  • Unwrapped in source: do not hard-wrap Markdown; let editors and renderers handle visual wrapping.

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 Rust-owned contract, 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 documentation anti-patterns ​

  • Duplication: same topic described in multiple places or the same information repeated in multiple ways.
  • Gratuitous cross-linking: links that repeat obvious navigation instead of adding signal.
  • Leaky layering: docs exposing internal implementation details.
  • Brittle examples: examples tied to unstable internal structures.
  • Over-documentation: documenting context that can be inferred from the code or that can be discovered elsewhere.

Minimalism is an asset. It reduces cognitive load, maintenance cost, and decision fatigue. It also creates a stronger signal when something is important enough to include.