Skip to content

Documentation Standard

Last verified: 2026-07-26 against dev at f0388abb.

Smart Document Processing documentation follows Diataxis plus a small product layer. Every new 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, models, or rules? docs/reference/ and component READMEs
Explanation Design context Why is the system shaped this way? docs/explanation/ and docs/design/
Runbook Production operation How do I safely change or recover production state? docs/runbooks/ or script-specific READMEs

Writing Rules

  • Do not mix tutorials with exhaustive command/reference material.
  • Do not put operational steps only in design docs. Add or link a how-to/runbook when an operator needs to repeat the task.
  • Do not duplicate full environment-variable tables. Link to the component that owns the config.
  • Mark design docs as draft, reviewed, approved, or historical.
  • Include organization/tenant assumptions on pages that touch assessments, documents, batches, extractors, or generated outputs.

Required Coverage

Each product repo 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.
  • At least one tutorial that gets a new contributor to a working local system.
  • How-to guides for common developer/operator tasks.
  • Reference pages for API, config, data model, and tenancy.
  • Explanation pages for architecture, processing flow, BYOK/key handling, and evaluation.
  • 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 known to describe legacy, draft, or in-flight work, state that near the top.