# Documentation Standards — Accessible Video Processing Platform

<!-- SCOPE: doc-standards | owner: ln-111 | generated: 2026-04-29 -->

## Core Rules

| Rule | Requirement |
|------|-------------|
| NO_CODE | No code block longer than 5 lines. Use tables, ASCII diagrams, or links to source files instead. |
| SCOPE tag | Every document must open with `<!-- SCOPE: {name} | owner: {ln-xxx} | generated: {date} -->` and close with `<!-- END SCOPE: {name} -->`. |
| Maintenance section | Every document must have a `## Maintenance` section at the end with: **Update triggers** (when to update) and **Verification** (how to confirm accuracy). |
| Canonical entry | All documentation is reachable from `AGENTS.md`. Never create a document that is an island. |
| No placeholder text | No `TODO`, `TBD`, `PLACEHOLDER`, `[describe here]`, or template metadata in committed documents. |
| No stale dates | Inline dates must be accurate at time of writing. Use `generated: {date}` in SCOPE tags rather than inline prose dates that rot. |
| Official links only | External links must point to official documentation (docs.python.org, fastapi.tiangolo.com, reactjs.org, MDN). No Stack Overflow, Medium, or blog links in reference docs. |

## Structure Rules

| Rule | Requirement |
|------|-------------|
| Tables over lists | Use markdown tables for: parameters, config values, comparison of alternatives, inventory lists. Use bullet lists only for sequential steps or genuinely unordered enumerations. |
| DAG navigation | Documents form a Directed Acyclic Graph. `AGENTS.md` → `docs/README.md` → domain docs. No circular links. |
| One canonical source | Every fact has exactly one home. Other documents link to it rather than repeating it. |
| File naming | Snake_case for all doc files. No spaces in filenames. |

## Document Types and Templates

| Type | Location | Contains |
|------|----------|---------|
| Root entry | `AGENTS.md` | Quick navigation, pipeline summary, constraints |
| Documentation hub | `docs/README.md` | Index of all docs |
| Requirements | `docs/project/requirements.md` | Functional requirements only (no implementation) |
| Architecture | `docs/project/architecture.md` | System design, state machines, data flow |
| Tech stack | `docs/project/tech_stack.md` | Dependency versions |
| API spec | `docs/project/api_spec.md` | Endpoints, auth, request/response shapes |
| Database schema | `docs/project/database_schema.md` | Collections, indexes, field definitions |
| Infrastructure | `docs/project/infrastructure.md` | Servers, ports, external services |
| Runbook | `docs/project/runbook.md` | Operational procedures |
| Principles | `docs/principles.md` | Engineering principles |
| ADR | `docs/reference/adrs/{date}-{slug}.md` | Single architectural decision |
| Guide | `docs/reference/guides/{slug}.md` | Developer how-to |
| Manual | `docs/reference/manuals/{slug}.md` | Operator procedures |
| Research | `docs/reference/research/{slug}.md` | Technology evaluation notes |
| Test docs | `tests/README.md` | Test commands, strategy, coverage |

## ADR Format (Michael Nygard)

| Section | Contents |
|---------|---------|
| Title | Short imperative verb phrase |
| Status | Proposed / Accepted / Deprecated / Superseded |
| Context | The problem or constraint that forced a decision |
| Decision | What was decided |
| Consequences | Trade-offs and impact |

## Maintenance

**Update triggers:** New document type added to the project, naming convention changes.
**Verification:** All committed docs have SCOPE tags. `grep -r "TODO\|PLACEHOLDER\|TBD" docs/` returns no results.

<!-- END SCOPE: doc-standards -->