Exercise 05: fix a poster

Goal. Make a small, correct improvement to a poster and see every check that keeps posters honest. Needs. the local setup with docs-site dependencies (make docs once). 30 minutes.

1. Find something to improve

Open any poster page — the request lifecycle is a good one — and walk it with Next. Find a caption that could be clearer, or a fact you can check against the file its footer names. (If you find a fact that is wrong, that is a bug: open an issue and fix it for real.)

2. Edit the spec, not the picture

Posters are generated: never edit docs/diagrams/posters/*.svg by hand. Edit the spec — docs-site/posters/08-request-lifecycle.mjs for that poster — change the caption in steps, and regenerate:

make posters
git status --short docs/diagrams/posters

Expected: the poster’s .svg and .steps.json show as modified. Now the drift check:

cd docs-site && node scripts/build-posters.mjs --check

Expected: build-posters: every poster is current. Try the reverse: edit the .steps.json by hand and run the check again — it reports the file as stale, because the spec is the source of truth. Regenerate to fix it.

3. See it

make docs-dev

Open the page, press Next to your step, and read your caption. Then run the gate the pull request would run:

make docs-check

Expected: 0 error(s). If you made the text too wide for its box, make posters told you already — the kit refuses text that overflows or is smaller than 16 px.

Self-check