Trying to not get too ranty about documenting software architecture

This article is my thoughts on a video about documenting software architecture:

A summary of the video is:

1. Domains other than software architecture, e.g. maps or electrical circuits, do a good job of capturing useful and important information in a way that communicates this well – this is mostly in pictures.
2. Software architecture does a poor job at this.
3. It is a problem to have too little documentation just as it is a problem to have too much.
4. The speaker presents a code-based lightweight modelling technique.

I had a mixture of reactions to the video – some bits got me surprisingly grumpy, and other bits I thought were excellent.

Part of what got me grumpy was what seemed to me to be snark.  This is probably me misinterpreting things, and probably best ignored (I’m just mentioning it here to be honest).

My bigger problem with the bits of the video relating to the first point above was undeclared assumptions that made things too simple and easy.  I.e. his point was stronger if you imposed restrictions that he was assuming rather than making explicit.

The maps he talks about are good for one main purpose – finding your way, which includes knowing where you are now.  However, there are other purposes where the map would work poorly and you would need some other kind of representation.  He ignores these purposes and the associated problems.  The purposes are answering questions like

• Where are the schools and what are their catchment areas?
• Who owns what?
• What purposes are allowed in different locations – homes, shops, offices, entertainment etc?
• How long will it take to commute by public transport to a particular location? This is addressed by e.g. Mapumental.
• What are the prevailing directions that commuters travel for different locations? (Some people will travel into a place for work while other people are leaving the same place to work elsewhere.)  What are the frequencies of the commutes and the distances involved?
• What is the variation of population density, crime rate, house prices etc. by location?
• Where are the sewers, gas and electricity mains?
• What are the Tube routes and stops, how often do the trains run and when are the first and last trains?
• How has the city changed over time?

Many of these can be addressed with a map plus something (some kind of annotation, colouring that represents information relating to a region etc.)  However, not all are that simple.  Even if you limit the list to just the purposes that need no more than an annotated map, if you tried to create a map that served all those purposes it would probably be an unreadable mess.

Because for him and many people finding your way is the most common GIS-related problem, it’s easy to ignore the others.  A software system isn’t the only thing where it takes more than one diagram to describe it in all the ways you need.  Even in built architecture like an office block, you would need separate diagrams for wiring, plumbing, escape routes, light and HVAC control areas, who rents what etc.  So, the distinction between software architecture and the rest of the world isn’t as stark as he suggests.

The code-based modelling technique looks very interesting, but unlike some of the diagrams he criticises, the diagrams it produces can’t answer questions like:

• Where does shopping (or some other functional requirement) happen?
• Where does logging (or some other non-functional requirement) happen?
• What bit of the system gets involved in security and when?

These are valid kinds of question, and it would take other diagrams to answer them.

I agree with his main point that it is a problem to have too little documentation just as it is a problem to have too much.  The things he proposes as needing documenting seem sensible, because they focus on the actual point of documentation for programmers: Good documentation will help you understand the code and hence make decisions about it when you’re changing it or debugging it.  It’s not about impressing people with how much you write, how well you draw, how big your vocabulary is.  It’s all about: Oh yes, now I get it. Therefore…

Documentation is needed for the information that you need to make these decisions that you can’t easily reverse-engineer from the code itself.  I think that this is true for all kinds of software documentation, e.g. comments, designs and tests (acting as documentation), but the big picture stuff is the hardest and most important of all as often this information is very thinly spread over a large body of code.

Overall, I got a lot of good stuff from the video.  The modelling technique looks like it’s worth investigating, and it’s important to remember the purpose of documentation.