Architecture, README, standards, CLAUDE.md, settings reference, indexes, backlog, release plans and CHANGELOG checked against the code at v2.14.0: backfeed, notifications, counts line and web actions documented; test policy (changed area locally, full suite in CI); stale versions, statuses and links fixed; legacy and superseded docs moved. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
3.5 KiB
Documentation Organization
Status: Active Last Updated: 2026-11-10 (v2.14.0)
docs/DOCUMENTATION.md is authoritative for what goes in which folder and supersedes this document. This standard only adds templates and conventions for writing the documents; it does not repeat the folder rules. If the two ever disagree, follow DOCUMENTATION.md and fix this file.
Layout at a glance
docs/
├── DOCUMENTATION.md folder rules (authoritative)
├── architecture/ current system design, refreshed each release; INDEX.md
├── decisions/ ADR-NNN-title.md; INDEX.md
├── design/ vX.Y.Z/ per release: designs, Q&A, reports, reviews; INDEX.md
├── projectplan/ BACKLOG.md, vX.Y.Z/RELEASE.md; INDEX.md
└── standards/ this folder; INDEX.md; DEPRECATED/ for retired standards
Outside docs/: README.md (overview and quick start), CHANGELOG.md
(every release), .env.example (every setting), CLAUDE.md (agent
instructions).
Conventions for every document
- Start with a
# Title, then**Status**and**Last Updated**lines (date and the release it describes) for documents meant to stay current (architecture, standards). - Link with relative paths (
../decisions/ADR-064-...md), never absolute filesystem paths. - Say what is true of the code now; history belongs in ADRs, design notes and the changelog. When describing something that changed, name the release ("since v2.8.1").
- Don't copy content between documents: link to the one place it lives.
Settings are documented in
.env.example, releases inCHANGELOG.md, the release process in git-branching-strategy.md. - Update the folder's
INDEX.mdwhen adding, retiring or renaming a document.
Architecture decision records
File: docs/decisions/ADR-NNN-short-title.md, next free number. Create one
when choosing between technical approaches, adopting a protocol, or
establishing a pattern. Template (as in ADR-064 to ADR-071):
# ADR-NNN: Title
## Status
Proposed | Accepted (vX.Y.Z, YYYY-MM-DD) | Superseded by ADR-MMM
## Context
The problem, constraints, and relevant spec (with link).
## Decision
What we will do. Numbered subsections for larger designs, citing spec
sections.
## Consequences
What gets better, what gets worse, what to watch.
## Alternatives considered
Each alternative and why it was not chosen.
## Amendments (vX.Y.Z, YYYY-MM-DD)
Later changes to the decision, newest last.
ADRs are not rewritten after acceptance. Change them with an Amendments section, or supersede them with a new ADR and set the old one's status to "Superseded by ADR-MMM".
Design notes
File: docs/design/vX.Y.Z/YYYY-MM-DD-topic.md, one folder per release
(rules in DOCUMENTATION.md). For format, see
version-implementation-guide.md.
Standards
File: docs/standards/topic.md. Each standard states what is required, why,
and how to check it, and is kept true to the code. A standard that no
longer applies is moved to docs/standards/DEPRECATED/ with a note at the
top saying what replaced it, and removed from the active list in
standards/INDEX.md.
Retiring other documents
- Architecture documents describing a design that no longer exists are
either rewritten or renamed with a
-legacysuffix and a note at the top (e.g.design/v0.x/technology-stack-legacy.md). - Design notes and ADRs are historical records and stay where they are.