Just-enough documentation for solo developers and small teams. Five files, not fifty pages.
Phase documents belong to waterfall. Research docs, plans of approach, requirements specs, design docs, test plans — written once, read never. Colophon replaces them with five living files that stay near the code, and grow with it.
In git, in markdown, reviewed in pull requests. Documentation that lives elsewhere rots elsewhere.
Write when a decision is made, a bug threatens to repeat, or someone will soon ask. Before that, you are guessing.
No mega-documents that try to be everything. Small files with a single focus stay accurate; sprawling ones don't.
The reverse test. Documents that cost time to maintain and solve no real problem are waste, no matter how professional they look.
A Brief, a folder of Decisions, a Log, a Runbook, a Changelog. Together they cover what waterfall tried to, with a fraction of the drag.
Detailed functional and non-functional requirements. Opt-in, for projects that prototype many capabilities before implementing them, or whose stakeholders formally require a spec. Most projects do fine without one — capabilities sit in the Brief, detail goes in the issue tracker.
# Decision 0003: SvelteKit for the PWA Accepted 2026-11-05 ## Context Frontend must be an installable PWA. Solo developer, fast iteration required. Options: React + Vite, Next.js, SvelteKit, SolidStart. ## Decision SvelteKit with adapter-static. ## Considerations Pro: smaller bundle, less boilerplate, built-in PWA support. Con: smaller ecosystem than React; may need to switch adapter if SSR becomes necessary later. ## Consequences - All frontend code in SvelteKit. - svelte-check added to CI. - No React components to reuse from other projects.
The Brief summarises and orients; Decisions capture trade-offs; the issue tracker manages live work; the Runbook handles operations. The optional Spec, when present, holds rich requirements detail. The map below shows the same content from two angles: traditional section for readers used to project plans, in Colophon for everyone.
| Traditional section | In Colophon |
|---|---|
| Purpose, scope, success criteria | Brief |
| Functional requirements (top-level) | Brief — Capabilities |
| Functional requirements (detail) | Issue tracker — or optional Spec |
| Non-functional baseline | Brief — Non-functional baseline |
| Non-functional trade-offs | Decisions |
| Stakeholders, roles, responsibilities | Brief — Stakeholders & roles |
| Planning, milestones | Brief (high) → Issue tracker (detail) |
| Risks (short) | Brief — Risks |
| Risks (large, with mitigation) | Decisions |
| Architecture, design rationale | Decisions |
| Test plan | Tests in code + a paragraph in the Brief |
| Deployment plan | Runbook |
The principle: Colophon documents what the project is. The issue tracker manages what the project does next. Mixing them produces documents that drift and trackers that go stale.
Do not document the past. Colophon is adopted forward: set up the skeleton, make the Brief current, and add new Decisions as you make them. Within thirty days you will have organically captured what matters.
Decisions are immutable once accepted. If you change your mind, write a new Decision that supersedes the old one — keeping the full reasoning trail. Future-you will know not just what was chosen, but why, and why it changed.
The Colophon template repository is a working example of the methodology — documenting itself in its own format. Fork it, rename it, keep what fits.