Colophon

A documentation methodology

Colophon

Five files, not fifty pages.

Colophon replaces phase documents — plan of approach, requirements spec, design document, test plan — with five living files that sit next to the code and grow with it.

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

Read the anatomy ↓ View the source ↗

Craft Code Systems · MMXXVI

The argument

Traditional project documentation is written when knowledge is lowest — at the start — revised rarely, and read almost never. For solo developers and small teams, the effort of producing it competes directly with the project itself. The documents grow long; the code drifts away from them; six months later nobody trusts either.

Colophon inverts the order. Documentation is written just in time: when a decision is made, when a bug threatens to repeat, when a specific reader needs the information. Each file has exactly one job, lives in git next to the code it describes, and stays short enough to actually be read.

The name comes from bookmaking. A colophon is the brief note at the back of a book recording how it was made — printer, typeface, paper, date. These files are the colophon of a codebase.

Five principles

Small rules, strictly kept.

Docs live next to the code
Markdown in the repository, versioned and reviewed like everything else. Clone the repo, get the docs.
Written just in time, not upfront
A file is added or updated when a real need triggers it — never to fill a template slot.
One file, one job
Each document answers one question. Overlap is where documentation goes to rot.
Decisions are immutable
An accepted Decision is never edited. Changed your mind? Write a new one that supersedes it. The old reasoning stays as history.
Minimal by default
Five file types. No more will be added. What the five cannot hold belongs in the issue tracker, a wiki, or another methodology.

Table of contents

Five files. One optional sixth.

README.md The Brief

Why the project exists, what is in and out of scope, how to run it, where it stands. One or two screens. Always current.

docs/adr/NNNN-*.md Decisions

One short file per design choice: context, decision, trade-offs, consequences. The memory of the project — why things are the way they are.

docs/research-log.md The Log

Append-only, dated notes from exploration. Rough by design. When a note crystallises into a real choice, it gets promoted to a Decision.

docs/runbook.md The Runbook

How to run, deploy, and unbreak the project. Written in a form that is useful at three in the morning.

CHANGELOG.md The Changelog

What shipped, when, following Keep a Changelog. The project's public history in human sentences.

docs/spec.md The Spec ^optional

Rich functional and non-functional requirements, opt-in only — for prototypes exploring many capabilities, or when a stakeholder formally requires one. Most projects never need it, and that is deliberate.

Specimen

docs/adr/0007-sqlite-over-postgres.md Decision

Decision 0007: SQLite over Postgres for v1

Status: Accepted
Date: 2026-05-14

Context

v1 targets a few hundred users on a single VPS. Postgres adds an operational dependency — backups, upgrades, connection pooling — that buys nothing at this scale.

Decision

SQLite in WAL mode, single file, backed up with Litestream.

Considerations

Pro: zero-ops, trivially fast at this scale, one-file backups.
Con: a future migration if write concurrency grows. Rejected: managed Postgres — cost and coupling without present need.

Consequences

ORM layer kept database-agnostic.
Migration threshold written down: >50 writes/sec sustained.

— 7 —

A complete Decision. Roughly one screen. Written the day the choice was made — and never edited afterwards.

A place for everything

Where the old sections go.

Colophon documents what the project is; the issue tracker manages what the project does next. Every section of a traditional project plan has a home:

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 trade-offs	Decisions
Stakeholders, roles	Brief
Planning & milestones	Brief (high) → tracker (detail)
Risks	Brief (short) → Decisions (analysed)
Architecture rationale	Decisions
Test plan	Tests in code + a paragraph in the Brief or a Decision
Deployment plan	Runbook

Adoption

Thirty minutes, then thirty days.

The 30-minute bootstrap

Triage the existing README: why, scope, how to run, status. Remove cruft.
Add the skeleton — docs/adr/, research-log.md, runbook.md, CHANGELOG.md.
Write Decision 0001: adopting Colophon. Meta, but your first working example.
Snapshot pre-Colophon history as a parking list in the Log. Not a commitment.

The 30-day rule

Explained an old choice to someone → Decision
Made a new design choice → Decision
Fixed a bug docs would have prevented → Runbook
Spent time investigating something → Log
Shipped something → Changelog

Notes & queries

Anticipated objections.

Is this just ADRs with extra steps?

No — Decisions are one of five types. The Brief, Log, Runbook, and Changelog each fill a role that Decisions alone do not. The synthesis is the method.

Doesn't the optional Spec break the "five files" promise?

The five core files stand for the default case. The Spec is an opt-in extension for the genuine minority — prototypes exploring many capabilities, or contracts that formally require a specification.

How is this different from Diátaxis?

Different scope. Diátaxis organises user-facing documentation; Colophon organises project-internal documentation — what developers and their future selves rely on. Use both if you need both.

I work solo — do I need this?

Especially then. Future-you is the most forgetful colleague you will ever have. A minimal setup costs ten minutes and pays off the first time you return after a month away.

What if my stakeholders demand a formal project plan?

Show them the coverage table above — every section has a home. If a separate deliverable is still required, write it as an export from Colophon, not instead of it.