Living documentation

Ordinary documentation asserts. A page says “a request with no signed-in learner is redirected,” and the claim sits there whether or not the system still does it. The page and the code are two sources of the same truth, and the moment one is changed without the other, they fork. The document does not announce the fork; it goes on asserting the old behaviour, quietly wrong.

A worked example is documentation that is executed. It is the same artifact the build runs as a check, so it cannot assert a behaviour the system no longer has — if it did, the check would fail. There is one source, not two, so there is nothing to fork. The reader and the build read the same words, and the words are kept honest by being run.

The value of living documentation shows the moment a behaviour changes. Take the three /my/courses examples. Suppose someone weakens the not-signed-in behaviour from “redirect” to “render whatever courses the request asked for”. With ordinary documentation, the page that described the redirect would keep describing it — now false, and no one is told, while the access rule is quietly broken. With living documentation, the not-signed-in example no longer matches the system, so the check fails: the documentation announces its own staleness instead of lying.

Toggle the not-signed-in behaviour below. With the toggle off, all three examples match the system and the documentation is current. With it on, the not-signed-in example fails — the figure reports the document as stale, not silently wrong. That failure is the signal to edit the spec and regenerate the example, the proper repair.

On the Portal — the learning platform this course builds — the protected /my/courses page carries its behaviour as three worked examples in its stories, settled at F6.5 · Views with HEExThe HEEx rung that server-renders the catalog and reconciles the learner route into the protected /my/courses.View the spec ladder →, and the rung's Definition of Done restates the access outcome. The page's documentation and its acceptance are the same lines: Portal.Enrollment over an unauthenticated request redirects — never another learner's courses. There is no second prose source to fall out of step.

The fragment below is spec text — the Definition-of-Done line paired with the matching Given/When/Then. If the not-signed-in behaviour changed, this example would fail; the repair is to edit the spec and regenerate, not to quietly correct the prose. Feedback edits the spec; the example follows.

# /my/courses — Definition of Done (F6.5): the documented outcome.
#   [ ] A request with no signed-in learner is redirected,
#       since /my/courses is protected — a learner never sees another's courses.

# stories — the same outcome, as the executable check.
#   Given a request with no signed-in learner,
#     when GET /my/courses,
#     then it redirects — never another learner's courses.

doc_line   = "not signed in → redirected"      # what the page says
check_line = "not signed in → redirected"      # what the build runs — the SAME line
drift      = :zero                          # one source; nothing to fork

A prose document and the code are two sources that fork when one is edited alone; a worked example is one source, read by a human and run by the build. Because it is executed, not asserted, it cannot describe a behaviour the system no longer has — a change that breaks the example breaks a check, and the documentation reports itself stale rather than lying. The repair is to edit the spec and regenerate. The closing dive names the mechanism beneath both moves: examples remove ambiguity, collapsing a requirement's readings from many to one.

The sources behind living documentation, and where it connects in the course.