video-accessibility-old/docs/documentation_standards.md

Documentation Standards — Accessible Video Processing Platform

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}
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.