The Unseen Cartographer: On Mapping a Tiny Service with a Hand-Drawn Diagram
We spend our days tending to small, intricate systems. We know their rhythms, their quirks, the specific sound a disk makes when a particular cron job kicks off. This intimate knowledge is our greatest asset, but it is also a vulnerability. It lives inside our heads, a fragile map drawn in neural pathways. What happens when the path is forgotten, or when someone else needs to follow it?
The instinct, when we think of documentation, is to reach for a digital tool. We might open a wiki or a README.md and start typing. But words on a screen can feel distant and abstract, failing to capture the spatial relationships and tangible flow of a service. There is a simpler, more fundamental technique I’ve come to rely on: the hand-drawn system map.
The Humble Ritual of Pencil and Paper
Once a quarter, or after any significant change, I perform a small ritual. I clear my desk, take a fresh sheet of paper, and a pencil with a good eraser. I do not open a terminal. I do not look at a config file. I start from memory, and I begin to draw. I sketch boxes for servers, circles for services, and arrows for the connections between them. I label the cron jobs, the log file locations, the backup destinations. I note the ports, the users, the little shell scripts that glue everything together.
The magic isn’t in the artistic quality—my diagrams are functional, often messy. The magic is in the act of reconstruction. Forcing my brain to retrieve the architecture from first principles invariably reveals a forgotten dependency, an assumption I hadn’t questioned, or a single point of failure I’d become blind to. The eraser is as important as the pencil; it represents the act of correcting my own flawed mental model.
This physical artifact then becomes something a digital document rarely is: a focal point. I tape it to the wall near my desk. It is not hidden in a folder or behind a login. It is always there, in my periphery. Its presence is a constant, quiet reminder of the system’s shape. When an alert fires at an odd hour, my eyes drift to the map before my hands even touch the keyboard, providing immediate context. When I need to explain the system to a colleague, I point to the paper. The conversation happens around a shared, tangible object, not a screen that divides us.
In an age of automated infrastructure diagrams and cloud visualization tools, this might seem quaint. But that’s the point. This isn't about generating a diagram for its own sake; it's about the process of creating it. The friction of drawing by hand is a feature. It forces deliberation and deep understanding. It is the act of an unseen cartographer, charting the known world of their small service, ensuring that no crucial path remains only a thought, and that no one who tends the garden after them has to start from a blank slate.
Notes & further reading
A few pages I came back to while writing this: