artifact-diagramming

Draw as the engineer who has to live with the decision, not as a decorator: a diagram earns its place when it lets a cold reader see a mechanism they would otherwise have to assemble from prose - where data flows, which components talk, what changes between two options, what state a request moves through. If a sentence says it faster, write the sentence.

What to draw

Depict the mechanism, not its name. A box labeled "cache" says less than the prose; the path a request takes through it, the two stores it sits between, and the arrow that disappears when the cache is removed say what the words can't. Show the parts that the argument hinges on - the boundary being crossed, the hop being added, the data that moves - and leave out the parts that don't.

Comparing options? Draw the difference. Two architectures side by side, a before and an after, the one edge that each option adds or removes - the reader should be able to point at what they are choosing between. A separate labeled box per option, with nothing connecting them to the system, is not a comparison; it is a restated option list.

Match complexity to the stakes. A one-hop question is a three-box diagram; a migration that reroutes writes through a queue needs the queue, the writer, the reader, and the ordering arrow. Draw as much as the decision actually turns on - no forced minimalism, no inventory of the whole system either.

Label the arrows. An unlabeled arrow is "related somehow"; writes, invalidates, polls every 30s is information. A legend is only worth it when the same encoding (dashed, colored, doubled) repeats; otherwise put the meaning on the mark itself.

Inline SVG mechanics

These mechanics apply where the page renders inline SVG natively (HTML pages); a markdown-rendered page draws its diagrams in whatever fence that lane's renderer supports, and the skill that owns the lane says which. An artifact made from an Artifact type draws its diagrams the way the type's instructions, and the reference pages they name, say to; these mechanics apply there only where those say nothing about diagrams. Hand-author inline <svg> with native shapes (rect, circle, line, polyline, path) and <text> - no libraries, no runtime, no external images.