Where have all the diagrams gone
Working software over comprehensive documentation is a principle from the original Agile Manifesto for Software Development. It’s a principle that is easy to adopt, particularly if you’re a dev that jumps at the chance to avoid writing documentation — docs are someone else’s job, right?
However, what happens when you have to communicate your system design outside the immediate team, to an external party such as an integrator, or an associate at a client?
I’m not talking about wireframes and screenshots here; I’m talking about system architecture, network diagrams, component and sub-system interactions — that stuff somebody created in simpler times when we used to do that waterfall thing. Now we are part of lean, Agile delivery systems, there is no place for the ancient artefacts created during those dark days. No one ever read them anyway!
Then, one day you’re just finishing your next feature-packed release and:
What! Somebody is actually asking for technical docs; you need them for a meeting, when?
When this happens, and believe me, it does happen, the docs are usually required in a timescale best measured in minutes! So we blow the digital-dust off our archive folders and seek out a few colleagues who used to do this sort of work. Then we find it. We discover a good one from a past project that we can repurpose and BOOM!
We have working software AND documentation. Smashed it!
I believe that the most useful technical documents aren’t weighty tomes, they are visualisations, the rough sketches we see on whiteboards, the designs made on bits of paper and the photos hastily taken on smartphones. These diagrams capture the amazingly valuable interactions between individuals on our teams (that sounds familiar). When appropriate, we should formalise and document these interactions — they are a sound basis for good diagrams.
My First Request:
Please think about putting effort into creating, and updating, technical diagrams of your systems following informal interactions. Stick them in source control where they can be seen, reviewed and updated.
Technical diagrams don’t have to take too much effort and can be a welcome diversion when you’re not under pressure to deliver them. They are a useful reference and a real aid to achieving a shared understanding amongst a development team. You could challenge a new team member to create them, or consider a whole team activity — this can act as a valuable exercise to get insight into how others think a system hangs together.
One More Request:
Before you fire up your diagramming tool of choice, I ask that you consider accessibility. Please don’t go crazy with colours; I have red-green colour blindness and sometimes struggle with diagrams that have an entire rainbow set of colours or poor colour contrast, and don’t get me started on random shapes, multiple line-types and missing legends.
If you’re stuck on where to start, try The C4 model for visualising software architecture. The C4 model appeals to my love of clear navigable diagrams. On his site, Simon Brown goes into quite some detail on the benefits of the C4 model. However, the small set of abstractions and diagram types, limited colour palette and self-describing entities are enough to make me happy — what about you?
