Documentation Placement Guide

Documentation Placement Guide

Where to put new documents. Use this before creating any documentation file.

---

Quick lookup

What you are writing	Where it goes
Architecture decision (durable, affects repo structure)	docs/adr/NNNN-short-slug.md
Architecture explanation (structure, patterns, rules)	docs/architecture/NN-short-slug.md
Operational procedure, rollout guide, incident playbook	docs/runbooks/topic-name.md
Active implementation plan or tracked initiative	docs/plans/
Stable technical reference for a subsystem	docs/reference/
Completed or obsolete plan/doc	remove from active docs (do not keep in docs index)
App-specific note tightly tied to one app’s internals	apps/{app}/docs/ — link from docs/README.md
Package-specific note tightly tied to one package	packages/{pkg}/ — link from docs/README.md if broadly useful
Informal scratch / working note	thoughts/ — explicitly non-canonical

---

Rules by section

docs/architecture/

Use for: repo structure, code placement rules, package categories, dependency constraints, runtime boundaries, naming conventions, generated artifact rules.

• These are authoritative and should reflect the actual current state.
• Update rather than add new conflicting docs.
• Number files sequentially (00-, 01-, …) to communicate reading order.
• If content becomes obsolete, remove it from active docs and update the replacement canonical doc.

docs/adr/

Use for: durable decisions that have a clear context, decision, and consequences. An ADR captures why a decision was made, not just what was decided.

• Format: NNNN-short-descriptive-slug.md (zero-padded 4-digit number).
• Status field: Proposed | Accepted | Deprecated | Superseded.
• Do not edit an accepted ADR to change the decision — add a new ADR that supersedes it and update the old ADR’s status.

docs/runbooks/

Use for: rollout checklists, incident playbooks, operational SLOs, troubleshooting guides, migration runbooks.

• Name by operational topic: {topic}-runbook.md, {topic}-rollout.md, {topic}-playbook.md.
• Group related runbooks into a subfolder if there are 3 or more related docs (e.g. docs/runbooks/eventbus/).
• Keep runbooks actionable: steps, commands, decision points.

docs/plans/

Use for: active implementation plans and tracked initiatives. A plan is active if work is still in progress or it is a useful reference for ongoing decisions.

• When a plan is complete, remove it from docs/plans/ and ensure any durable outcomes are reflected in architecture, runbooks, or reference docs.
• Plans may be folderized for multi-ticket initiatives.
• Plans are not ADRs — if a plan produces a durable decision, capture that in an ADR.

docs/reference/

Use for: stable technical reference for specific subsystems (not how to operate them, not decisions about them — just what they are and how they work).

• Reference docs should stay current as the system changes.
• Keep reference docs factual and descriptive.

App-local and package-local exceptions

A document may remain outside docs/ if it is tightly coupled to a single app or package and would not be useful to developers working elsewhere in the repo.

Criteria for staying local:

• The document is only meaningful if you are actively working on that app or package.
• It references internal conventions or internals not visible outside the app/package.
• Keeping it near the code makes it easier to maintain.

Even if a doc stays local:

• Add a link from docs/README.md under App-Local and Package-Local Docs.
• Clearly note why it is local in the docs index.

Examples of legitimate local docs: apps/dashboard/AGENTS.md, apps/dashboard/docs/CSRF_PROTECTION.md, tests/AGENTS.md.

---

Non-canonical areas

• thoughts/ — informal scratch and working notes. Nothing here is authoritative. Outputs worth keeping should be promoted to a proper docs section.
• plans/ (root) — deprecated. All new plans go into docs/plans/.

---

Lifecycle rule

A document is active if:

• it describes how the system currently works, or
• it tracks ongoing work that is not yet complete.

A document is inactive if:

• the work it tracks is complete, or
• it describes a system state that no longer exists, or
• it has been superseded by a newer document.

When a document is no longer active, remove it and carry forward any durable guidance into canonical docs.