There's an interesting discussion on the 97 Things Every Software Architect Should Know discussion group (LinkedIn) about how to document software systems, which has inspired this short blog post.
Since the code doesn't tell the whole story, I believe that all software teams should deliver some form of supplementary documentation. It must be lightweight and useful though. I think of such supplementary documentation as being a software guidebook and I use my C4 approach to create a set of simple software architecture sketches.
To be honest, many typical software architecture document templates aren't actually too bad as a starting point for supplementary documentation, but often the names of the various sections confuse people. If you glance over the list of section headings in my software guidebook, you might be wondering where the typical software architecture "views" are.
If you've not seen these before, there are a number of different ways to look at a software system. Examples include IEEE 1471, ISO/IEC/IEEE 42010, Philippe Kruchten's 4+1 model, etc. What they have in common is that they all provide different "views" onto a software system to describe different aspects of it. For example, there's often a "logical view", a "physical view", a "development view" and so on. The big problem I've found with many of these approaches is that it starts to get confusing very quickly if people aren't versed in the terminology used. For example, I've heard people argue about what the difference between a "conceptual view" and a "logical view" is. And let's not even start asking questions about whether technology is permitted in a logical view! Perspective is important too. If I'm a software developer, is the "development view" about the code, or is that the "implementation view"? But what about the "physical view"? I mean, code is the physical output, right? But then "physical view" means something different to infrastructure architects. But what if the target deployment environment is virtual rather than physical? My advice is, however you write documentation, just be clear on what it is you're trying to communicate and name the section accordingly. One option to resolve the terminology issue is to ensure that everybody on the team can point to a clear definition of what the various architectural views are. Software Systems Architecture by Eoin Woods and Nick Rozanski comes highly recommended in this regard. Another approach is to simply rename the sections to remove any ambiguity.