Anatomy of a roadmap.md

The roadmap is the delivery layer in one plain file. It answers what ships, and in what order — never how a thing behaves. Three parts carry it: milestones that name shippable outcomes, the rungs that climb to each one, and a definition of done every rung must meet. Select a part to see what it holds.

The parts Thin but robust References

A roadmap.md · select a part

Rungs are the thin, ordered steps that ship the milestone — each one valuable, each one provable, each pointing at the spec that defines it. The arc is the build order; start at the top.

The parts of a roadmap

A roadmap.md is short on purpose. It holds three kinds of thing and nothing else: milestones — shippable outcomes a person would notice, like “a learner finishes a lesson”, not internal tasks like “add a table”; the rungs that climb to a milestone, each a thin slice of value that points at the spec defining it; and a definition of done that says, once, what finishing any rung means. Behaviour lives in the specs the rungs point at — never here.

Read top to bottom, the rungs are the build order. Each is small enough to ship on its own and ordered so the earliest ones already deliver something; the milestone is reached when its rungs are all done. A concrete skeleton:

# Portal — roadmap

## Milestone 1 · a learner finishes a lesson
goal: a person can enrol and complete one lesson, end to end

- [ ] R1.1  enrol a learner          → spec: enrolment.md
- [ ] R1.2  deliver the first lesson → spec: delivery.md
- [ ] R1.3  record completion        → spec: completion.md

## Definition of done (every rung)
stories pass · invariants hold · quality gates green

Milestone: A shippable outcome a person would notice. Groups the rungs that, together, deliver one increment of value.
Rung: One thin, provable step toward a milestone. Valuable on its own, ordered in the climb, and pointed at the spec that defines it.
Definition of done: Stated once, for every rung: stories pass, invariants hold, quality gates green. “Done” is a closure over checks, not a feeling.

Thin but robust

The hardest word in a roadmap is thin. A good rung is a narrow slice that still goes all the way down — through the surface, the logic, and the data — so the increment actually works end to end. Cut too narrow and you ship a façade that demos but does nothing; cut too wide and you are back to a big batch no one can review. Thin but robust is the line between them.

The roadmap is where that judgement is recorded: each rung is sized so it is small enough to prove and complete enough to ship. Select a cut to see the difference.

The cut · select one

Thin but robust: a narrow slice that still reaches every layer, so the rung works end to end. Small enough to prove, complete enough to ship — the size a roadmap aims for.

A roadmap is a ladder of thin-but-robust rungs. Size each so it proves something and ships something; the spec it points at says what “works” means.

References

Primary sources for this deep dive, and where it connects in the course.

Sources

Humble, J. & Farley, D. — Continuous Delivery — the delivery layer: milestones and releasable increments.
Hunt, A. & Thomas, D. — The Pragmatic Programmer — tracer bullets and walking skeletons.
Beck, K. — Extreme Programming Explained — small, shippable increments.