Files
StarPunk/docs/standards/documentation-organization.md
T
PhilandClaude Opus 5.5 0716984958 docs: Bring all documentation up to date for v2.10.1
- architecture/: overview, technology stack, auth (OIDC + built-in
  IndieAuth), syndication (POSSE) rewritten; new database.md,
  deployment.md and indieweb-protocols.md; legacy stack marked historical
- decisions/: reconstructed ADR-060 and ADR-063; 31 status corrections
  (superseded auth ADRs, proposed -> accepted); INDEX rebuilt
- design/: reconstructed the v1.6.0 documents the webmention code cites;
  reports for 18 v2 releases without a design folder; INDEX rebuilt
- projectplan/: BACKLOG rewritten (shipped items removed, open issues from
  the reviews added); RELEASE.md for v2.0.0-v2.10.1; INDEX
- standards/: development setup (uv, tests, DEV_MODE), testing (CI test
  stage), git and release flow, versioning, coding standards, cookies
- README, CLAUDE.md, .env.example (every setting the code reads, with
  defaults) brought up to date
- 137 broken links repaired (old absolute paths, moved files); stale ADR
  references in code comments corrected (comments only)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 12:40:19 -07:00

3.5 KiB

Documentation Organization

Status: Active Last Updated: 2026-11-03 (v2.10.1)

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. architecture/technology-stack-legacy.md).
  • Design notes and ADRs are historical records and stay where they are.