Fleet docs v0.2.0-rc.448

Write a story

A story is an animated, step-through diagram on the /docs site: stops joined by tracks, tokens that move along a track, and one caption per step. It is data: one file, docs/stories/<name>.json. You never touch the player (fleet/internal/docs/assets/stories.js).

Put one in a page

Write the marker on the line right before the Mermaid block, and keep the Mermaid block:

<!-- story: sign-in-device-flow -->

On GitHub the Mermaid shows. On /docs the story is drawn in its place. The Go test (make -C fleet check) fails when a marker has no file, when a Mermaid block has no marker, and when a story file is not valid.

The file

{
  "w": 1000, "h": 360,
  "alt": "what the picture shows, one sentence",
  "zones": [{"x": 20, "y": 20, "w": 460, "h": 300, "label": "node-a"}],
  "lanes": ["cli", "server"],
  "stops": {
    "cli": {"x": 130, "y": 60, "color": "you", "label": "fleet CLI", "sub": "on the laptop", "side": "up"}
  },
  "tracks": [{"from": "cli", "to": "server", "bend": [0, 0, 0, 0]}],
  "steps": [
    {"caption": "One plain sentence. `code` in backticks.", "label": "text on the token",
     "moves": [["cli", "server"]], "bad": ["server"], "fix": []}
  ]
}
  • w (default 1000) and h are the picture size. The page scales it to the screen, so it never scrolls sideways. A phone shows it small: keep labels short, and prefer fewer stops.
  • stops: x, y, color (you, agent, worker, server), label, sub (\n breaks a line), side where the text sits (down default, up, left, right), anchor (start, middle, end) to shift it.
  • tracks: a line between two stops. It has a direction: a move goes along from to to. A reply needs its own track the other way (give both a bend so they do not lie on top of each other, for example [0,-30,0,-30] and [0,30,0,30]). bend is [dx1, dy1, dx2, dy2], the two curve handles relative to the ends.
  • steps: each has a caption (what happens, in plain words) and optional moves (each must be a track), label (a short message on the first token), bad (stops turn red from this step on) and fix (clears them). A step with no moves just shows the caption.
  • lanes: stops that drop a dashed life line downward. With stops placed at the same y in a row and more stops below them (one per message), this gives the look of a sequence diagram.
  • zones: a labelled box behind stops, for a machine, a cluster or a fleet.

A diagram that has no sequence (a layout of parts) is a story of one step, or a few steps that light up the parts one group at a time.

Rules

  • Say only what the code does. Mark a planned thing as planned in the caption, with its issue.
  • Name roles, not people or companies: "chief", "orchestrator", "node-a".
  • The Go test estimates the width of every label. It fails when a label overlaps another label, a stop or a track, or leaves the picture. Fix it by moving the stop, changing side, or shortening the text, not by loosening the test.
  • Open the page and look at it. Try the first step and the last at phone width.
  • Preview: run a scratch server that calls docs.Handler. #step=3 on the address opens every story on step 3.