Notes on explaining systems to other people

You have seen the diagram that was accurate on the day it was drawn and wrong two sprints later — the queue that is not on it, the retry path that never made it in. Two things do that. A picture in a wiki does not diff, so nobody corrects it. And a static picture shows every arrow at once, which is not how the system behaves: a request takes one path, in one order, and the picture says nothing about that. So whoever drew it ends up narrating over the top of it, tracing the route with a cursor.

This is where we write down what we learn about that problem: patterns we had to draw before we were sure we understood them, arguments about what belongs in a diagram and what is noise, and the syntax we use to write flows as text — User -> API Gateway -> Lambda -> DynamoDB for a path, SNS -> {Email, SMS, Push} for a fan-out, LLM -> |Tool, Response| for a branch.

It is written for the people who have to explain a system to other people: engineers, architects, developer advocates, consultants. Posts aim to end with a few lines you can paste straight into the editor, and where another tool is the better answer for the job, we would rather say so.