A3.3 · Anatomy of a roadmap.md · dive 1
What it carries
A complete chapter roadmap carries six parts, each answering a different question — and none of them defining behaviour.
Read them in order on the real phoenix.roadmap.md and the shape of the
document becomes a template. Pick a rung on the right to watch one roadmap line decompose into its rung, its
milestone, the spec it points at — and the behaviour it defines, which is always none.
Decompose one roadmap line · pick a rung
The six parts, in order
A chapter roadmap is a structured document. phoenix.roadmap.md carries six parts,
each a named section, each answering a different question:
- delivering
- What we are delivering — the destination, verbatim: “The Portal, served to people: a real web application that renders the catalog, lets learners enroll and progress…”.
- handoff
- Where this starts and ends — the boundary, verbatim: “Start (the F5 handoff).” in, and “End (after F6.9).” out.
- architecture
- Architecture decision — standard Phoenix on the BEAM, verbatim: “The stack is standard Phoenix, Ecto, and LiveView on the BEAM — the conventional, well-supported path — with no separate frontend application.”
- milestones
- The delivery arc — three milestones, verbatim: “1 · Ship the catalog”, “2 · Make it live”, “3 · Ship to users”.
- the table
- Per-rung iterations — the per-iteration table (the A3.3.2 dive): rung · ships · demo · harness · feedback asked.
- decisions
- Seams & open decisions — the named, unresolved choices (the A3.3.3 dive).
Over all six sits the master invariant, verbatim: “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.” In the file's own words, “This single rule is what makes
the ladder cheap”.
A part answers a question, a line points at a spec
The six parts are the document's anatomy; within the delivery arc, each rung is one line. A rung line does four things and no more: it names the rung, it belongs to a milestone, it points at a spec, and it leaves behaviour to that spec. The hero figure decomposes a single line into those four facets — the fourth, behaviour, always reads none.
The part picker below walks the whole anatomy instead of a single line. Select a part to see its question and a verbatim phrase from the file. The two figures teach different moves: the hero zooms into one line, this one steps across all six parts.
Each part answers a question · pick one
Six parts, six questions, one invariant — and within the arc, each rung line points at a spec and defines no behaviour.
What it carries, on the Portal
On the Portal — the learning platform this course builds — the real artifact is
phoenix.roadmap.md, the delivery plan for the web chapter F6. It carries the six
parts in order, and within the delivery arc the per-rung table lists nine rungs f6.1
through f6.9. Each row is one line that ships a slice; each points at its
f6.N.md spec, where the behaviour is actually defined.
The line is coarse on purpose. “f6.1 — the engine served as a web app” orders the work and names a demo; the contract — the request path, the facade call, the rendered error — lives in the spec the line points at. The roadmap holds order; the spec holds behaviour. That separation is what lets the next dive re-order the rungs without editing a single spec.
# phoenix.roadmap.md — the per-rung table (a line per rung; verbatim cells). # | Rung | Ships (the slice) | Demo | # | f6.1 | the engine served as a web app | hit the root, see a page | # | f6.5 | the rendered catalog (index, course_card, ...) | browse the catalog | # A rung line decomposes into four facets — the fourth is always "none". line = "f6.1 — the engine served as a web app" rung = "f6.1" # names the rung milestone = "1 · Ship the catalog" # belongs to a milestone spec = "f6.1.md" # points at a spec behaviour = :none # the line defines no behaviour # All of it under the master invariant: the web layer calls only the Portal facade.
A roadmap carries six parts — deliverable, handoff, architecture decision, milestones, the per-iteration table, the open decisions — and within them each rung line points at a spec and defines no behaviour.
phoenix.roadmap.md carries all six; its per-rung table lists
f6.1…f6.9, each pointing at its f6.N.md spec, all
under the master invariant.
A roadmap line is the coarse face of a rung — it orders and points; the spec it names is where the behaviour lives.
Recap — six parts, no behaviour
A chapter roadmap carries six parts: what it delivers, the start/end handoff, the architecture decision, the milestones, the per-iteration table, and the named open decisions. Each rung line within the arc names its rung, belongs to a milestone, points at a spec, and defines no behaviour — all over one master invariant. With the anatomy in hand, the next dive reads the operational heart of it: the per-iteration table.
Next in A3.3: A3.3.2 · The iteration table — each row a rung, and why re-ordering the rungs edits no spec.
References
The delivery-planning sources behind the roadmap's anatomy, and where it connects in the course.
Sources
- Humble & Farley — Continuous Delivery — each rung a thin, demoable slice down a delivery pipeline.
- Hunt & Thomas — The Pragmatic Programmer — tracer bullets and the orthogonality the facade boundary preserves.
- Beck, K. — Extreme Programming Explained — the planning game: order the work, defer the design.
Related in this course
- A3.3 · Anatomy of a roadmap.md — the module hub.
- A3.3.2 · The iteration table — the next dive.
- A3 · The roadmap layer — the orientation dive this expands.
- A1.04 · Two layers — the roadmap over the spec.
- A0.2.2 · The four artifacts — the spec a rung line points at.
- F6 · The Portal on the web (Phoenix) — the real chapter this roadmap plans.