Skip to content

Documentation Standard

Last verified: 2026-07-26 against current checkout c09254f.

DocGen documentation follows Diataxis plus a small product layer. Every page should have one primary purpose.

Doc Types

Type Purpose Reader question Location
Product Product context and scope What is this, who is it for, and what does it do? docs/product/
Tutorial Guided learning How do I get one successful first result? docs/tutorials/
How-to Task execution How do I complete a specific task? docs/how-to/
Reference Exact facts What are the APIs, config keys, roles, models, or contracts? docs/reference/ and component READMEs
Explanation Design context Why is the system shaped this way? docs/explanation/
Runbook Repeatable operations How do I safely run or recover an operational procedure? docs/runbooks/
Record Project history What was planned, designed, or decided at a point in time? docs/releases/, docs/design/, docs/solutions/

Writing Rules

  • Keep tutorials short and guided; link out to reference for exhaustive fields/endpoints.
  • Keep how-to guides task-oriented and executable.
  • Keep reference pages factual and stable; avoid narrative justification there.
  • Keep explanation pages focused on concepts, architecture, and tradeoffs.
  • Keep PRDs, TDDs, plans, specs, and audits as records; do not silently rewrite historical intent when current docs can point to the shipped behavior instead.
  • Do not duplicate long endpoint/config tables. Link to the owning reference or component README.
  • State org/tenant assumptions on any doc that creates, seeds, or scopes solution data.
  • Do not document a back door around the /v1 config API as a preferred path.

Required Coverage

DocGen should include:

  • docs/README.md as the canonical documentation entrypoint.
  • docs/product/overview.md.
  • docs/product/users-and-use-cases.md.
  • docs/product/capabilities.md.
  • docs/product/status.md.
  • At least one tutorial that gets a new contributor to a working local system.
  • How-to guides for authoring, seeding, MCP, observability, and solution onboarding.
  • Reference pages for API, configuration, domain model, and tenancy.
  • Explanation pages for architecture and rendering/prompt behavior.
  • A runbook index.

Freshness

When a page is materially reviewed, update its Last verified line with the date and branch/commit. If a page is a historical record, keep its original status but link to current docs where behavior has moved.