Writing the docs
How these pages and their imagery are produced.
Content and site are separate
| Where | What it is | |
|---|---|---|
| Content | docs/content | The documentation. MDX, plus the walkthroughs. |
| Site | docs-site | A renderer. Fumadocs on Next.js, deployed to Vercel. |
| Capture | docs/capture | The harness that generates screenshots and recordings. |
The split is deliberate: documentation outlives whichever renderer is in front of
it. Replacing docs-site should not require touching a single content file.
Imagery is generated, never authored
Nobody takes a screenshot by hand. Each walkthrough is a committed step list that the capture harness replays against the running product. One run produces both the numbered stills the page embeds and the recording at the top.
node docs/capture/capture.mjs # every flow
node docs/capture/capture.mjs sign-in # one flowCapture output is committed for now, so the site has imagery without needing a running app in CI. It is still generated, never edited by hand — if a picture looks wrong, fix the step list and re-run the capture rather than touching the file.
Why it is done this way
A screenshot rots faster than the prose around it, and a rotted screenshot is worse than none — it shows a screen that no longer exists, and readers trust pictures more than words. Because each flow declares which screens it is made of, a change to one of those screens can be made to fail the build until the imagery is re-shot.
There is a second payoff: a replayable step list is also an end-to-end test. When replay breaks, either the docs went stale or the product regressed, and both are worth knowing.
Adding a walkthrough
- Explore the screens and pick stable selectors.
- Write
docs/capture/flows/<id>.json. Captions are the documentation prose — write them for someone doing the task, not for a developer. - Fill in
dependsOnso staleness is detectable. - Run the capture, then add an MDX page using
<Walkthrough>and<Step>.
The full playbook, including every trap that cost real debugging time, is in
docs/capture/PLAYBOOK.md.