As an Architect one of the frustrating things, is writing an Architecture Document to communicate your designs. Over my many years of writing these documents I have constantly ran into the issues of getting the correct balance, to end with a useful document. After attending the Principals of Architecting Software Systems from IBM I was conscious that the Architecture Documents that I was writing, had changed for the better.
To make a document useful there are a couple of traits that I observed:
- Focus the document on specific audiences
- Document the decision process that got you to your design
- Architecturally Significant: Focus the document on areas that effect the design
The big one from my perspective is being able to include in your document an understanding of the alternatives that were considered. When you review an Architecture you are focusing on the design being the best design for the problem that is being solved. So from an authors perspective you want to capture the conceptual ‘decision tree’ that you would have gone through to come to the final design. If some one reading the document can see logical decisions that shaped the solution then your document often answers the questions your audience has.
The areas in the the document that capture this information are:
- Architectural Goals: Is there a target architecture that this solution is trying to drive the technology landscape towards.
- Constraints: There are often project and organisational things that limit or shape the design decisions for a project.
- Assumptions: Some decisions can only be based on an assumption documenting these assumptions is a way to CYA.
- Issues and Risks: When you consider the project that will implement your design and the environment where it will live once it is built there are issues that you know exist and risks that could eventuate, some of these will influence your design and some just need to be noted.
- Exclusions: It is as, if not more important, to spell out what your design does not attempt to do.
Understanding the relevance of these sections better, I have now got to the point of writing them last even though they are at the start of the document. Once I end up with a design that I feel is solid and provides the correct solution to the problem, I then by writing each of these sections challenge the design to make sure everything has been considered.