Software Architecture Document Guidelines

v0.1 - a work in progress

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 :

  1. An outline description of the software architecture, including major software components and their interactions.
  2. A common understanding of the architectural principles used during design and implementation.
  3. A description of the hardware and software platforms on which the system is built and deployed.
  4. 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.

About the author

Simon lives in Jersey (the largest of the Channel Islands) and works as an independent consultant, helping teams to build better software. His client list spans over 20 countries and includes organisations ranging from small technology startups through to global household names. Simon is an award-winning speaker and the author of Software Architecture for Developers - a developer-friendly guide to software architecture, technical leadership and the balance with agility. He still codes too. You can tweet Simon at @simonbrown.



Re: Software Architecture Document Guidelines

This post got attention on InfoQ.com in their Architecture community.
Here's the link: http://www.infoq.com/news/2008/03/architect-resources
Great post.

Re: Software Architecture Document Guidelines

Hey Kevin Very nice and useful document. What about the development of this document. I see it has been alive since the midst of March. Is there a newer version? What are the plans and timelines for newer versions? Regards, Owin

Re: Software Architecture Document Guidelines

I think it's Simon that deserves most the credit for the SAD guidelines, not me! But I'll take it nonetheless :P

Thanks for the comment. Mid-march wasn't all that long ago but we're always working on new content and updating other pieces so if there's anything specific you think is missing from the guidelines or needs further detail then please let us know so we can get that into the next version.

Re: Software Architecture Document Guidelines

Hahahaa...Very true that it's not a long time ago. I have the feeling it's May for some reason. 2 things that I first notice (without having actaully used it yet) - chapter 2 an 15 seem like they can be one - the checklists could be extended Regards

Re: Software Architecture Document Guidelines

This document is a masterpiece even though it is V0.1 I can't believe the clarity with which the requirements of what such a doc should cover are conveyed. I've been looking for something to convey to a team and we are not using any bloated methodologies at this time. I find that the trick is first to convey what is required and tools are just there to help, but the requirement of what goes into such a doc is not first understood then tools are a waste of time (i.e. garbage in, garbage out). I find that a lot of sites and companies punting methodologies leave this out and one simply gets lost/bogged down in a quagmire of technobabble that is meaningless. This document at least sets an expectation (or objectives) against which you can measure any document that is produced. In closing, do you have anything against someone like myself utilising sections of this almost verbatim? Once again thanks for a very imformative document!

Re: Software Architecture Document Guidelines

Thanks Greg, glad you're finding it useful. No objections, feel free to use it as a basis for your own work - just make a reference to where you found it. :-)

Re: Software Architecture Document Guidelines

Many thanks Simon!... Will do One more thing, do you have anything covering what a Functional Requirement type doc should convey?... Including installation and support documentation (for operational teams)

Re: Software Architecture Document Guidelines

Hey Simon, I like this doc very much. Version 0.1 has been around for a while. When do you expect an update? A question I have is why chapter 2 and 15 are seperated? I've used the doc a few times now and always end up merging the 2. Are there plans for merging them in future versions? Greetz

Re: Software Architecture Document Guidelines

I think it makes sense to keep the non-functional view and justification separate.

In my mind, the non-functional view captures the non-functional requirements - it sets out what your architecture is trying to achieve. This is sometimes a document in its own right, sometimes owned by someone other than the architect. Nonetheless, the audience is often non-technical, being required to agree that your interpretation of the NRFs is correct and complete.

The justification of the NFRs is for traceability, to show that the proposed architecture is up to the job. Again, this could be separate, the results of prototyping or industry benchmarks.

For certain sets of requirements there's no doubt benefits to merging the two, perhaps where a simple "requirement/design decision" matrix will suffice.

Is it worth us adding something to the guidelines to capture this flexibility or even creating an "SAD-lite" version?

Re: Software Architecture Document Guidelines

Hey Kevin, Thanx for the fast reply. I agree on the non-tech/tech division. What I don't like is repeating stuff, especially if this stuff is relatively far away from eachother in a document. What happens when a NFR changes? You would change them in both chapters. maybe it's an idea to make subchapters 2a and 2b (or 2 and 3), so they are closer together?

I'm always a fan of 'lite' versions, but how would this version differ from the current version, other than what we are talking about?

Greetz, Owin

Re: Software Architecture Document Guidelines

If you have identifiable NFRs then the justification section is more a foreign key relationship than a denormalised view ;)

As for their juxtaposition, I have wondered about that in the past. Sometimes it's easier to reference the design decisions after they've been presented, sometimes it's not... The SAD is often better as a hyper-linked tree of information than as a linear Word document in either case. The subtree of interest (and reading order) should be dependent on the viewer's need, not the author.

There are other similar synergies a lite version could appeal to: logical and interface views can often be superimposed, the design view might be driven by the functional view, the deployment view is often implicit in the infrastructure view. That said, most of this could simply be covered by the removal of a section from the existing SAD guidelines.

Re: Software Architecture Document Guidelines

I agree that it should be written for the reader. Often though, in my case anyway, the readers are pretty technical people and would want to know how we cover the NFRs. So I would like a 'lite' version very much! But the question is if the group would want to develop and maintain 2 versions. I recon more people don't like to have the same stuff in more than one place ;) Owin

Re: Software Architecture Document Guidelines

With you now... sorry, the suggestion was more that there were two templates, one for technical, tactical or derivative projects and another for slightly more green-field ones. Certainly not implying that you'd maintain two version of the SAD for a project (although you might want to offer several views onto a Wiki or similar).

Re: Software Architecture Document Guidelines

Just thought you should know, there is this brilliant person out there who thinks just like you - so much so that he's come up with all your ideas, mostly word for word, and put them on his blog:

http://blogs.msdn.com/sachinrathi/archive/2008/11/17/architecture-specification-brief-what-should-it-include.aspx

Re: Software Architecture Document Guidelines

Thanks for the heads-up ... I'm pretty amazed that somebody from Microsoft would do that in public! :-)

Re: Software Architecture Document Guidelines

Thanks! Really useful.

Add a comment Send a TrackBack