I led an architecture discussion at a major bank last week and one of the questions that came up was, "how much detail do you put in your software architecture document?". Specifically, the question was focussed on the software design aspects of the architecture. Let's say that you're building a web application and you've decided that your architecture document is going to contain a high level view of the technologies and components that will be used for the implementation. Let's also say that you've decided to use UML to describe it.
So then, how much detail do you include? My take on this is "just enough". I don't subscribe to the theory that the architecture document needs to include everything right down to the very lowest level of detail. I think too much time is wasted getting down to that level and, in doing so, you increase the likelihood and speed at which the information becomes out of date. Keeping UML diagrams up to date can be a particularly time consuming exercise if you've modelled every aspect of your software.
Instead, what I do is ensure that there's enough information to document the high level concepts and enough guidance to support the development team. As for the UML diagrams, I use them to illustrate concepts and only include the essential information. This might sound a little wooly, so let me put it like this. If you ask somebody to implement some functionality on your webapp and they ask you the following sort of questions, you probably don't have enough detail.
I'm not saying that you should just write the architecture document and then hand-off the subsequent work to the rest of the team, but there should be enough guidance in the document to answer all of the frequently asked questions. Think patterns, principles and examples rather than detailed blueprints and precisely detailed models.
Simon is an independent consultant specializing in software architecture, and the author of Software Architecture for Developers (a developer-friendly guide to software architecture, technical leadership and the balance with agility). He’s also the creator of the C4 software architecture model and the founder of Structurizr, which is a collection of open source and commercial tooling to help software teams visualise, document and explore their software architecture.