architecture diagrams · production grade

A diagram is an argument, not a picture: drawing systems people can act on

Almost every architecture diagram is drawn for the person who drew it. It shows everything they were thinking about, at every level of detail at once, on the day it happened to be true. Then it is presented to four different audiences who each needed a different picture, reviewed by someone whose first five questions it cannot answer, and consulted at three in the morning by an on-call engineer who finds it is eleven months out of date. Eleven sections on drawing the other kind.

Try it: score a diagram you have actually got

Try this: think of a diagram in your own repository or wiki and tick what is genuinely true of it. The score is less interesting than the order the missing items come back in. Some of these cost far more than others.

in real lifeA car's MOT checklist. The tyres matter more than the wing mirrors, and a list that treats them equally is not much help when you have an hour.

start bytick nothing at first and read the top item on the missing list.

words herelegend the key saying what a line, colour or shape meansstale the diagram no longer matches the real systemcritical path the route through the system that actually matters

Try it: spend the first ten minutes

Try this: forty minutes on the clock and six things you could do. Pick them in the order you would actually do them, and watch the clock. The commonest mistake is not a wrong answer, it is starting to draw in minute one.

in real lifeA doctor's appointment. Ten minutes, and the ones who ask three questions before reaching for the prescription pad are not being slow.

start bypick draw the containers first and read what it says.

words herecontext diagram your whole system as one box, and who talks to itcontainers each separately deployable piecescope what you are deliberately not covering