thinkingengineeringwork

Diagrams I keep redrawing

Alex, senior software engineer and author of Alex's Whiteboard blog

Alex

· 5 min read

There's a section of my office board that I've been drawing the same diagram on for six weeks. It's a data pipeline — three sources, two consumers, a transformation layer in the middle that keeps changing shape every time we learn something new about the upstream schema.

I draw it, live with it for a few days, notice something wrong, erase part of it, redraw it. Repeat. The diagram has probably existed in fifteen different versions by now. I don't save any of them. Each one is the current best understanding.

This is something I've come to think of as the board's best use case: problems that need to be lived with. A document can hold a bad model indefinitely because updating it feels like a chore. The board invites revision. It costs nothing to erase. The friction of keeping a wrong version is higher than the friction of drawing a better one.

The diagram I have up today looks nothing like the first version. The first version was clean and confident and completely wrong in about four ways. I knew it was wrong within two days of drawing it, but I could articulate exactly how, which is more than I could say for the week before I drew anything at all.

There's a version of this story where I put it in Miro or Lucidchart and edit it digitally. I've done that on other problems. It works, but it doesn't feel the same. Digital diagrams are easy to make look finished. A whiteboard diagram always looks provisional, which is honest, because it is.

The pipeline problem is nearly solved now. I expect I'll draw the final version this week and it'll stay up until the implementation ships. Then I'll erase it and move on to whatever comes next.