a documentation methodology

Colophon

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.

The manifesto

Five principles. Read them once.

Docs live next to code.

In git, in markdown, reviewed in pull requests. Documentation that lives elsewhere rots elsewhere.

Just-in-time, never upfront.

Write when a decision is made, a bug threatens to repeat, or someone will soon ask. Before that, you are guessing.

One document, one job.

No mega-documents that try to be everything. Small files with a single focus stay accurate; sprawling ones don't.

If nothing breaks when it's gone, don't write it.

The reverse test. Documents that cost time to maintain and solve no real problem are waste, no matter how professional they look.

Five files beat fifty pages.

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.

The anatomy

The five document types.

Brief

README.md

The project's one-page orientation. Why it exists, what it does, where to start.

Decision

docs/adr/NNNN-*.md

One short file per significant design choice. Immutable once accepted.

Log

docs/research-log.md

Dated, append-only notes from exploration. Rough by design.

Runbook

docs/runbook.md

How to run, deploy, and unbreak this thing. The 3am-friendly file.

Changelog

CHANGELOG.md

What changed and when. Written for humans, not diffs.

A specimen

What a Decision looks like.

# Decision 0003: SvelteKit for the PWA

**Status:** Accepted
**Date:**   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.

In the wild

Existing projects, and changing minds.

Adopt it in a project that already exists

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.

The 30-minute bootstrap →

When a structural choice changes

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.

Worked supersession example →

Begin

Fork the template. Start in minutes.

The Colophon template repository is a working example of the methodology — documenting itself in its own format. Fork it, rename it, keep what fits.

View on GitHub Read the manifesto

$ gh repo create my-project --template Craft-Code-Systems/colophon