Docs / Writing diagrams

Notes, branches and dividers

The statements that turn a list of calls into a story a reader can follow.

Messages tell readers what happens. Notes, branches, dividers and delays tell them why, what else could happen, and how the story is paced.

#Notes

A note is a box of explanation. Where it sits depends on how you write it:

volley

title: Three kinds of note
order: Browser, Shop, Payments
Browser -> Shop: GET /orders/42
note: Spans the message above it
note Payments: Sits on one lane
note Browser, Payments: Spans a range of lanes

#Multi-line notes

Write note: (or note A, B:) with nothing after the colon, then the note on the following lines. The note runs until the next statement. Multi-line notes take full Markdown: paragraphs, lists and fenced code.

note Browser, Payments:
**Why two calls?** The shop creates the charge first so it can
retry safely with the same idempotency key.

1. Create the charge
2. Confirm it
```
Idempotency-Key: order-42
```

Like payloads, a multi-line note ends at the first line that reads as a statement. Put code that might look like a statement inside a fence.

#Branches with if and else

Use if to show alternatives, most often the success and error paths of a call. Close the section with end:

volley

title: Card payment
order: Shop, Payments
Shop -> Payments: POST /charges
if: Card accepted
  Payments --> Shop: 200 OK
else: Card declined
  Payments --> Shop: 402 Payment Required
  out: Error
  ```json
  { "error": "card_declined" }
  ```
else
  Payments --x Shop: Timeout
end

• Each else starts another branch. Labels are optional: else on its own is fine.
• if without a label works too.
• Indenting the contents is optional but makes the source easier to read. The editor indents for you after you press Enter on an if, else or group line.
• Each branch can answer the same request with its own reply, as above. See Replies and response pairing.
• Forgetting end is an error, Section opened here is never closed with "end", reported on the line that opened the section.

#Groups

group draws a labelled box around steps that belong together, without implying a choice:

group: Fulfilment
  Orders -> Warehouse: Reserve stock
  Orders -> Shipping: Book a courier
end

Groups can hold else branches too, which is handy for "one of these happens" cases that are not really conditions.

Sections can sit inside other sections. One level of nesting is easy to read; more than that usually means the diagram should be split.

#Dividers

A divider is a horizontal rule across every lane, with optional text. Use dividers to split a long flow into chapters.

volley

title: Divider styles
A -> B: Before
_: thin
-: regular
--: dashed
=: bold
A -> B: After

#Delays

A delay shows that time passes between two steps:

Shop -> Customer: Order confirmation
...: {fas-hourglass-half} Three days later
Courier -> Customer: Delivered

... on its own draws a delay with no text.