demo

Demo

A demo shows data, not code or a summary of code: a real request, a real row, a real file, a real command and what it printed. Demo what the user named; with no target, demo the work done so far in this session.

Before designing an interactive demo, read Red Blob Games' Making of: Circle drawing tutorial as the quality benchmark for teaching through interaction.

What counts as a demo

Show the data crossing the system's boundaries, in the order it crosses them:

• In at the edge — the HTTP request and response on the wire, the CLI invocation, the input file, the message off the queue
• Through the work — the command that does the thing, run for real
• Into storage — the SQL that executed, the rows before and after, the on-disk representation
• Out to the human — the page, the terminal, the report, the screenshot

Reading code aloud, a table of what changed, a test-passed count, or "the system now correctly…" is not a demo.

Capture with Showboat, never author

Every byte of output comes from a tool that recorded it while the command ran. Never retype, tidy, reconstruct, or predict output. If it was typed, it is prose; evidence comes from a capture tool.

Showboat builds the document, via uvx showboat (or uv tool install showboat):

uvx showboat init demo.md 'One POST, end to end'
uvx showboat note demo.md '## The table starts empty'
uvx showboat exec demo.md bash 'sqlite3 app.db "SELECT count(*) FROM note;"'
uvx showboat image demo.md screenshot.png

• exec appends the command and its captured output, prints it, and exits with the command's status
• note carries all prose: framing, what to look for, caveats
• image copies a screenshot or recording into the document
• pop removes the most recent entry

Make it verifiable

showboat verify demo.md re-runs every block and fails if output drifted. Aim for a demo that passes, which requires idempotence: reset state inside a captured step (a first block that empties the table), not off-camera before recording. When a demo cannot be idempotent, run verify anyway and note in the document which blocks drift and why.