September 12, 2006
The Software Architecture Document
On the previous post I pointed out some of the possible stakeholders who would be interested in a software architecture document (SAD). In this post, I talk a little about the structure for such a document.
The first thing that should be clear that (unless it is a specific requirement by the client) is that writing a SAD is not a goal in itself. It should be a useful document or it will end right there in the big pile of write-only-documents -- which means it was a waste of time. Take a look at Scott Ambler's essay on "Agile Documentation". I would suggest following these guidelines on both small and large projects.
The second thing to keep in mind is that a SAD is not the place to dump all the output that your {insert favorite case tool here} can generate (and/or reverse engineer). Putting everything in the SAD is just another way to make it, yes you've guessed it--a write-only-document.
The third thing to keep in mind is that you don't have to make the SAD overly formal, the formality level should be driven by customer requirements otherwise just make it useful. (yes I know it is re-iterating the first rule -- but it is important)
The questions is, of course, how do you make it useful?
The key issue here is know who you are writing it for. Since the SAD has many potential readers, a SAD document needs to have several views. Each view can cater to the need of specific stakeholders from their specific viewpoint (IEEE standard 1471-2000 "IEEE Recommended Practice for Architectural Description of Software-Intensive Systems" has a nice and useful model that defines the relations between stakeholders and the architecture documentation). One useful thing you can do is to develop a catalog of useful views and then when the need arise draw on that catalog. RUP offers four views (Process, Logical, Development, physical, plus one on requirements), RM-ODP offers five views (computational, Technology, engineering, information, and enterprise), Zachman has 36 views (I am not going to list them all) , FEAF has 15 etc. One conclusion we can have is that views are indeed, very popular. For us, these are just list of possible views to consider when we need to document something for a stakeholder.
While the list of views is dynamic and optional, one chapter I almost always have is "Rationale, Background and Constraints" this chapter includes:
- Architecture Principles. A few easy to remember guidelines for the architecture including rationale and trade-offs.
- Constraints. Any constraints placed by stakeholders (technological or otherwise), including rationale and implications.
- Utility Tree. Quality attributes and scenarios for the architecture.
- Architecture Overview. A high-level overview of the architecture (main layers, components, relations) and key alternatives (if applicable).
- Future Growth. Expected extension points.
While all this sounds very formal (and it usually is (since I work with clients who usually demand formal
documentation and I still try to keep it concise ) I again remind you that the SAD need not be too formal or to picky in regard to what gets documented . Also remember that maintaining documentation up-to-date is costly only so only document the bare minimum that is useful.
P.S. Two good books that discuss the issues of documenting software architectures are:
Posted by Arnon Rotem-Gal-Oz at 06:20 AM Permalink
|
