Files
StarPunk/docs/standards/documentation-organization.md
T
PhilandClaude Opus 5.5 ceef048003 docs: documentation review for v2.14.0
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>
2026-11-10 14:51:57 -07:00

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 in CHANGELOG.md, the release process in git-branching-strategy.md.
  • Update the folder's INDEX.md when 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 -legacy suffix 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.