a3b300b76a
- AGENTS.md: canonical project entry point (Quick Nav, pipeline, constraints) - docs/: complete docs tree — architecture, API spec, DB schema, infra, runbook, requirements, tech stack, principles, reference ADRs, guides, tasks backlog, testing strategy - tests/README.md: test commands, structure, known gaps - README.md / CLAUDE.md / DEPLOYMENT.md: updated with canonical doc links - .archive/: backup of pre-documentation-pipeline originals - backend/uv.lock: uv dependency lockfile - Delete committed __pycache__ .pyc files (should have been gitignored) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
61 lines
3.6 KiB
Markdown
61 lines
3.6 KiB
Markdown
# 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 -->
|