Coding the Architecture - software architecture document tag

Documenting your software architecture - why and how?

Mon, 19 Oct 2009 12:39:57 GMT

Another of the sessions that I delivered at the recent Software Architect 2009 conference was entitled "Documenting your software architecture - why and how?" and covered some of the drivers for creating software architecture documentation along with some guidelines on how to do this. As I said in the session, any software architecture documentation should be complementary to the code and describe what the code itself doesn't. For example, it's really hard to identify things like architectural principles, operational aspects and how security works from just the code itself.

As with Broadening the T, I'm going to put one or more essays together that cover the content in more detail. In the meantime, you can view or download the slides.

How big is your software architecture document?

Wed, 16 Apr 2008 20:30:00 GMT

I'm going to write-up my notes from the last London user group (Sharing Architectures) later in the week, but I wanted to pose a question to you that I asked at the user group. How big is your software architecture document for your current project/system and what sort of information does it contain? Here's a graph summarising the size responses from the user group (small turnout this month).

As you can see, most people's software architecture documents are ~50 pages and above, which my experience suggests isn't uncommon. How does this compare to yours and does anybody read these documents?

Is UML on the way out?

Thu, 03 Apr 2008 19:32:00 GMT

One of the presenters at QCon (I think it was John Davies) asked the audience whether they used UML 2.0 and only a couple of people raised their hands. I wasn't one of them - I briefly looked at UML 2.0 a while back but I didn't feel compelled enough to use it. This got me thinking, how widespread is the use of UML nowadays?

From my own perspective, here's where I tend to use UML within the context of a bespoke software project.

Use case diagram : A high level view of the system functionality and scope.
Activity diagrams : A high level view of the business process that is being realised by the software. This is useful for showing parallelism.
Class and sequence diagrams : Information about architectural patterns and blueprints (e.g. describing a common implementation pattern). These are typically used by the development team.
Component and deployment diagrams : Details about deployable components and how instances of those components will be/are deployed on pieces of hardware.

As I've mentioned before, I tend to go with a just enough approach to the software architecture document, but I do definitely find that UML is useful because you don't have to think about the notation. Having said that, I do use Visio-style block diagrams for representing things like the logical and physical/infrastructure architecture (you can see a simplified version of such a diagram on page 3 in this presentation). I do this for two reasons. First of all, I don't think that UML provides an easy to understand notation for this sort of thing and second, these high-level architecture diagrams are typically distributed to a wider audience, some of who aren't technical and don't understand UML.

So then, is UML on the way out? I'd be interested in your thoughts on the following.

What notation do you use for your architecture and design diagrams?
Is a standard diagramming notation important to you?
How does your audience influence how you create diagrams?
If you do use UML, what's your UML tool of choice?

Software Architecture Document Guidelines

Tue, 18 Mar 2008 15:36:00 GMT

Update, 27th October 2009: Please see Software architecture document guidelines for an updated version of the guidelines.

Regardless of the development process that you use, a description of the software architecture can be essential for any project, big or small. If software architecture is about the structure of a system and is the vehicle for satisfying the requirements, then the software architecture document is a written description of this. My simplified view of the content included in a software architecture document is :

An outline description of the software architecture, including major software components and their interactions.
A common understanding of the architectural principles used during design and implementation.
A description of the hardware and software platforms on which the system is built and deployed.
Explicit justification of how the architecture meets the non-functional requirements.

During our tutorial last week at QCon, we asked attendees to define the software architecture for a small software system and provided a handout containing some guidelines. Since this may prove useful for other people, we're making Software Architecture Document Guidelines v0.1 available for download.

It's worth remembering that the software architecture doesn't have to be a huge weighty tome and it doesn't even need to be a traditional Word document. What's important is that you capture the important architectural decisions and principles. This set of guidelines includes suggestions for what you might want to include. Just as a final note, this set of guidelines is a work in progress and we'll be iterating it over the coming months. Any feedback is welcome.

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.