Last week I drew a large diagram of the Digital Marketplace’s technical architecture on a whiteboard, for the benefit of some people outside the team (and some people relatively new to the team). It took me about 15 minutes to draw it, as we have a lot of components. At the end of the session I was asked, quite reasonably, if I could capture what I’d drawn and add it to our documentation. I think there was some surprise in the room when I said no!
The truth is we already have several diagrams in our technical documentation, of varying levels of detail. Everything I’d drawn on the board was already documented in at least one of those diagrams, probably with a neater arrangement of boxes and arrows, and a more consistent level of detail across the architecture. For example, as well as a basic top level architecture map, we have a diagram for our data model, one for our AWS permissions model, one describing how our application logs and metrics work… you get the idea. Our architecture hasn’t changed much in the last year, so the documentation is all reasonably up to date.
So why draw the diagram on the whiteboard in the first place? Why not point the newcomers to the shiny pictures in our docs beforehand, and save time in what was a pretty lengthy meeting? Well, the usefulness of those docs depends on the audience. A technical architect, who is new to your specific project, will be used to reading technical documentation and diagrams. If they read through the docs beforehand, the component names and user journeys may be unfamiliar, but they will know roughly what technologies to expect and where to look for things. They can then come to the meeting prepared with any questions they have. Similarly, someone in a non-technical role may have been working on the project for a while, but perhaps needs a reference diagram: they will recognise the labels and flows on the diagram, and can work out where their knowledge gaps are, ready for the meeting.
For a new team member who isn’t in a technical role though, coming face-to-face with a giant spidery mess of boxes and lines can feel like an insurmountable challenge! Having an experienced person explain each part of the system as it appears can be a lifesaver. At the beginning, there won’t be too much on the board, and things will feel less overwhelming. Questions can be asked at any point. Seeing an arrow being drawn in a particular direction may help cement in the memory how (and why) data flows from one app to another. Hearing the full names of components said out loud can demystify space-saving acronyms. There are more subtle benefits as well: the drawer may use their body language or intonation to emphasise the importance/grouping of certain elements. That’s much harder to reproduce in a PNG!
If I had captured my diagram into a static image as I was asked, it would have fossilized. Those nuances would have been missing. It would have been less streamlined and accurate than our existing docs, and probably more confusing! Also, the audience has now changed: the people who were in the room are now more familiar with our system, and our once-baffling docs should now be more penetrable. There are also potential accessibility issues around complex diagrams: an accompanying verbal explanation may be essential if the diagram is not annotated appropriately, which realistically, I would not have had time to do in this case.
My caveat for refusing the polite request was that I would be absolutely willing to spend another 15 minutes in the future re-drawing and re-explaining a real-time diagram, to anyone who wants to listen! Just like Tony Hart.