A3.3 · The roadmap layer
Anatomy of a roadmap.md
A chapter roadmap is a structured document, not a to-do list. Read a real one part by part and its shape becomes a template you can reuse.
The exemplar is the Portal's real web chapter — F6 (Phoenix) —
and its phoenix.roadmap.md: nine rungs f6.1…f6.9,
three milestones, each rung a line that points at a spec and defines no behaviour, all under one master
invariant. Pick a part on the right to see what it carries.
The six parts of a roadmap · pick one
Six parts, one invariant
A chapter roadmap answers six questions in order, and each is its own section in
phoenix.roadmap.md. What we are delivering states the destination.
Where this starts and ends names the handoff in and the end state out.
Architecture decision records the one structural choice and its reversible cost.
The delivery arc groups the rungs into three milestones. Per-rung iterations
is the table where each rung ships a slice with a demo and a harness. Seams & open decisions
names what is not yet decided and where it will be.
Over all six sits the master invariant, quoted verbatim from the file: “The web layer calls only the
Portal facade and renders only the closed %Portal.Error{}
set. No controller, LiveView, plug, or template names Portal.Engine, a repo, or
GenServer.call.” It is the rule every rung holds, and — in the file's own
words — “This single rule is what makes the ladder cheap”.
A roadmap has a fixed anatomy — deliverable, handoff, architecture decision, milestones, the per-iteration table, and the named open decisions — and reading those parts is how you learn to write one.
phoenix.roadmap.md carries all six parts, under the master invariant. Each rung is
a line that points at its f6.N.md spec and defines no behaviour.
Read a real roadmap part by part, and the document becomes a template — six sections over one invariant.
The three dives
Each dive takes one part of the anatomy, in the arc what a roadmap carries → the per-iteration table → the open decisions: first the whole anatomy, then the operational table at its heart, then the decisions a roadmap names but does not resolve. Read them in order — A3.3.1 starts.
What it carries
The six parts read in order on the real file: what it delivers, the handoff, the architecture decision, the milestones, the table, the open decisions — and none defines behaviour.
The iteration table
The operational heart: each row is one rung — ships, demo, harness, feedback asked. Re-order the rungs and the spec-edits counter stays at zero.
The open decisions
What the roadmap names but does not decide — auth, deployment, the dashboard — each deferred to a rung, each bounded by the same master invariant.
A3.3 expands the orientation dive A3
· The roadmap layer, which framed the layer; here the anatomy is read part by part on the real
phoenix.roadmap.md. Return to the
A3 chapter navigation to continue.
References
The delivery-planning tradition this anatomy draws on, and where it connects in the course.
Sources
- Humble & Farley — Continuous Delivery — releasing in thin, demoable increments down a delivery pipeline.
- Hunt & Thomas — The Pragmatic Programmer — tracer bullets and naming what is not yet decided.
- Beck, K. — Extreme Programming Explained — small releases and the planning game over an ordered backlog.
Related in this course
- A3.3.1 · What it carries
- A3.3.2 · The iteration table
- A3.3.3 · The open decisions
- A3 · The roadmap layer — the orientation dive this module expands.
- A1.04 · Two layers — the roadmap over the spec.
- A0.2.2 · The four artifacts — the spec the rung points at.
- F6 · The Portal on the web (Phoenix) — the real chapter this roadmap plans.
- Companion · Functional Programming in Elixir