Me again. For one of the projects I’m currently overseeing at work I made a couple of videos to explain our current architecture.

I did this because I needed to explain a bit about it at out big team meeting (the one with product managers, delivery managers, people outside of Customer Products etc etc), but when I simply drew the diagrams and photographed them there was too much information to show on one slide and get people to look at.

It made me realise that much of the value in drawing a diagram is the actual act of drawing it. So instead of popping the finished sketch on a slide I tried to capture the act of drawing it instead.

Here is an example:

What is this format good for?

In Giles Turnbull’s Agile comms handbook he talks about the three layers of comms, and these videos are in the context layer.

These are scrappy, and that’s good

Anybody with a deep familiarity with the system is going to find a bunch of problems with these diagrams. They don’t contain all the detail; I’ve missed off everything to do with authentication, cacheing, logging, and some other content APIs.

Those diagrams also exist but they are the detail layer, not the context layer, where we give people “just enough” information to see if they want to know more or if they have what they need and can go on with their life.

These are hard to edit, and that’s good

Another feature of these diagrams is that they are hard to edit. This is really handy, provided they are “correct enough” at the time, anybody who comes to them later will consider them an artefact of a moment in time, rather than an ongoing living document.

We have a lot of “living documents” at the FT, detailed Miros, or Lucids, or UMLs, which are out of date and nobody knows if they are allowed to update them, or how out of date they are. This kind of impossible to edit sketch is very appealing. The format is aligned with the intent of the content. “Here is a sketch, don’t take it too seriously, if you find it in 2 years stuff might have changed”.

Hold tight for the science bit

If you’ve read this far and think you’d like to give this a go - here are some details on how I did it. I have a tripod, and I used my iPhone’s to capture me drawing and then fiddled with the speed in iMovie. It did take me a couple of goes to draw the diagrams in a way I was happy with.

Then I used iMovie to narrate over the top of the captured video. I also found it helpful to add in a title card, mainly so I could see in the movie thumbnail what the video was going to be of. I hardly ever use iMovie, which is free with my Mac, and doing this was pretty easy.

When I tested playing a video and audio in Google Meet I got an echo on the audio so for any actual meetings in which these are presented I’ve disabled the audio function.

These videos take a lot of inspiration from Vi Hart’s maths explainers from… oh god eleven years ago. I met Vi once at a conference and I asked her to say “snake snake snake” and she did it, which was very cool of her and very goofy of me to ask.