An architecture diagram can show a handler, an authorization service, and a renderer. A new engineer tracing a failed document preview still needs to know which path applies, where access is denied, and which source lines support the explanation.
A useful explanation should let the reader follow that question without losing the connection to the implementation. Living Explainers explores this idea through an authored model that generates a self-contained HTML page.
Start with a request path
The bundled example follows a document preview through validation, access review, and rendering. It contains three authored paths: success, denied access, and renderer timeout.
A reader can choose a path, inspect its steps, and look at source references and assumptions. A question about caller retries is explicitly outside the model's coverage. That boundary is useful: an explanation can show what it covers without inventing the behavior of the rest of the system.
The model distinguishes observed, documented, and proposed material. A proposed step should remain visibly proposed even if it sits beside a source-backed step in an attractive interface.
Generate the offline explorer
Use Python 3.11 or newer for the CLI. It needs no third-party runtime dependencies:
git clone https://github.com/asadani/living-explainers.git
cd living-explainers
out_dir="$(mktemp -d)"
python -m living_explainers validate fixtures/model.json \
--root fixtures/system
python -m living_explainers check fixtures/model.json \
--root fixtures/system --out "$out_dir/freshness.json"
python -m living_explainers build fixtures/model.json \
--root fixtures/system --out "$out_dir/explorer.html"
The fixture validates as a model with five nodes and three paths. Its recorded source baselines are current, so the check exits successfully. Open explorer.html in a JavaScript-capable browser to explore it.
The output does not need a running application server. It contains a snapshot of the authored model and freshness information at build time. It does not fetch source files or monitor the repository after it has been exported.
Treat source changes as a review request
Source references retain file fingerprints and cited line ranges. A changed source can mark affected references stale; a missing file remains visible as missing. Material without a reviewed baseline remains unreviewed.
Running the renderer again cannot silently bless a new version of the source. Refreshing a baseline is an explicit review action after someone checks the referenced material.
This is conservative. The fingerprint covers the whole source file, so an unrelated edit can ask for review even if the explanation's cited behavior is unchanged. That creates maintenance work, but the alternative would require a stronger method for deciding which changes invalidate an explanation.
The distinction between building and reviewing is the design point: rendering an explanation and accepting its evidence are different operations.
An authored model still needs an author
Living Explainers does not infer architecture from a repository, execute the described system, or discover new failure behavior. Someone must choose the scope, write the steps, connect them to source, and review the claims.
That effort should earn its place. For a tiny function, a short explanation beside the code may be easier to maintain. A bounded request flow with multiple paths is a better candidate for an explorer because the reader has meaningful choices to inspect.
Visual polish also cannot establish teaching value. The current fixture demonstrates an interface and its maintenance mechanism; it does not establish that engineers learn faster with it.
Evaluate one concrete reader task
Choose a request that newcomers need to trace. Ask them to identify the access-denial boundary or the safest location for a change, using either the current documentation or the explorer. Record whether their answers are correct, which evidence they consult, and where the model leaves them uncertain.
Then change a referenced file and measure the author's maintenance effort. An explanation that helps readers today but is too costly to review next month may not be an improvement.
The MIT-licensed repository contains the request model, synthetic source fixture, renderer, and design plan.
AI disclosure: This article was drafted with AI assistance using the project source and documentation. The examples are synthetic; no improvement in reader comprehension is claimed.
Top comments (0)