How much software design detail in your architecture document?

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.

About the author

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.

You can find Simon on Twitter at @simonbrown ... see for information about his speaking schedule, videos from past conferences and software architecture training.

Re: How much software design detail in your architecture document?

If folks are interested in more detail about the principals of modeling (architectural or otherwise) in a relatively "light" manner, Scott Ambler's website, Agile Modeling is fantastic.

He lists the values, principals and practices for modeling which can indeed be summed up as you stated, "just enough".

Re: How much software design detail in your architecture document?

While I disagree with statements like "the code is the architecture", I'd be tempted to answer most the questions you cite with, "what's already in the code/reference architecture?" - or question why it isn't in the reference architecture!

Answers to questions like, "what should I log?", "when should I get data from the database" aren't usually so salient in code. These principles feel like they belong in the SAD, as do any exceptions to existing principles and reasons behind important design decisions.

It seems that what I'm saying is that I put as little software design "detail" into my SAD as I can! Some, sure, but it's not where I spend most time.

Add a comment Send a TrackBack