Software Architecture Document Guidelines
v0.1 - a work in progress
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.
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.
Simon is a hands-on software architect who works within 
