How much software design detail in your architecture document?

Fri, 18 Jan 2008 12:14:00 GMT

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.

Patterns are about experience...

Tue, 31 Jan 2006 17:02:15 GMT

Why software patterns are important is a good post about why patterns are important within the context of being an architect.

In general term Patterns can help by trying to identify common solutions to recurring problems. The interesting thing of pattern is that they are captured by experience. They aren't designed upfront in a speculative way. They emerge from the field, from real software that works, from real teams.

...

Pattern reading is an important activity for every software architect which hasn't a valuable experience. I think that pattern studying is an important activity in any computer science curricula. Students can learn a lot about software design and architecture without waiting to hurt in the war's field of a software development job.

Essentially, this is saying that while you can't gain real-world experience from reading, you *can* gain insights into what works and what doesn't. This is an important part of an architect's role and helps you make those critical decisions that balance the functional and the non-functional requirements.

Coding the Architecture - patterns tag

How much software design detail in your architecture document?

Patterns are about experience...