Patterns vs blueprints
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.
- What technology should I use to implement this?
- Which framework are we using?
- How do you want me to implement logging?
- How should I get data from the database?
- Why are we using X instead of Y?
- How is component X supposed to call component Y?
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.