A diagram shows everything at once, which is why it explains nothing. Here a flowchart written in Mermaid's syntax is laid out by dagre, drawn in the kit's ink by Rough.js, and then walked: a character goes node by node along the edges, the node lights up, and a bubble says what that step is for (the %% note lines). The diagram is the stage; the explanation is the script.
The chart is text (a subset of Mermaid)
flowchart LR or TD · A[box] B(rounded) C{decision} D((circle)) · A --> B · A -->|label| B · A --- B (no arrow) ·
%% note A: what the walker says here · %% path A,B,C (the order to walk; without it, every node in layout order) · %% walker oto
What this taught us
- The notes are the storyboard. The chart's nodes are the panels' settings; the
%% notelines are the lines spoken. Writing the notes made it obvious which nodes were two steps pretending to be one. - Layout is somebody else's problem, and should stay so. dagre (96 KB, MIT) placed every example first time; the kit should draw what a layout engine returns, not grow its own.
- A walker needs a path, not a graph. Explaining is linear even when the chart is not;
%% pathis the author's choice of the one story through the diagram, and a decision node wants the "yes" and "no" branches walked as two short paths. - Mermaid's syntax is enough, and it is already everywhere. Reading a subset of it means a chart from a README can be explained without being redrawn. What the subset lacks (subgraphs, styles) is what an explanation rarely needs.
- The camera wants to follow. On a tall chart the walker leaves the screen; zooming the viewBox to the current node (the Camera experiment) is the next step.