Who Needs a "Software Architecture Document"?

You architected your best solution ever. You have a dozen prototypes to prove your points. You've prepared an architectural skeleton that shows how things work together end-to-end and maybe a few recipes to show developers how to implement important "stuff". Is that enough?

Well, sometimes it can be enough, but often it isn't. The main reason it might not be enough is that the developers are not the only stakeholders interested in the architecture who need to understand the architecture. Who are the stakeholders that may need a software architecture document? They include:

• Project newcomers. The developers already on the team live the architecture and the design. Newcomers need some "signposts" to help them discern what's important and what's not.
• Maintainers. Like project newcomers they need a good guide to help them along. The also need to understand the environment that the development team used (what version of Eclipse, which version of Tibco EMS, do they need Spring? etc.).
• Your replacement (the person who will inherit the project when you move to a better job). She will need more than just signposts. She would also need to understand the rationale behind the decisions you've made.
• System engineers in multi-disciplined projects. The system engineers need to gain some understanding on the architecture (mostly deployment diagrams but they can also be interested in security or safety views of the systems).
• IT team--client's or in-house. They need to understand the implications of the system (deployment/components, security). They need to understand the "what."
• Technical representatives of the client. They need to understand the overall picture, how the solution takes care of the major quality attributes (how do you handle that 1million hits per hour requirement?). Rationale for decisions, options you didn't choose, etc.
• Client . Clients are usually not technical people, but they might want to see that their core requirements are somehow addressed.
• Developers. Sometimes they'll also want to have a document as reference for important decisions.

Occasionally an architecture document is a requirement by the customer. When you decide you need one or when the customer wants you to write one, there are several things you need to watch for to make sure that the software architecture document is useful and doesn't turn into a write-only document. I'll talk about a few of these concerns on the next post.

Posted by Arnon Rotem-Gal-Oz at 06:07 AM  Permalink