What should be in an Architecture Document?

Recently, I was asked by a colleague how an architecture document should look like? What are the basic rules each document should follow and how should all documents be related to each other? Obviously, there is no standard template applicable to each project context. However, there are some attributes a really good architecture document should reveal:

• Introduce special documents on the domain model (if applicable), on central issues such as patterns used, and on different kinds of guidelines. Make sure all architecture documents comply with these guidelines.
• Don't extend 50 pages per document. A large document with more pages will not be read by anyone, at least not all its content.
• This is a no-brainer. But nonetheless, I am going to mention it: Use a standard document template.
• Structure all documents exactly the same way. Otherwise, readers won't feel comfortable, especially when they have to read more than one architecture document.
• Describe the software architecture top-down. Start with the basic abstractions and then step by step move to more concrete details and implementation issues. This way, different readers can read the document according to the detail level they need. For instance, a manager might only be interested in the coarse grained architecture while engineers are also interested in deployment issues. A good way is to use the 4+1 view of the IBM Rational Unified Process. In the beginning, explain what part of the architecture you are actually describing in the document including its motivation and scope. Then address all requirements that have influenced your architecture (decisions) as well as the relevant use cases that drive the architecture design. A context diagram helps to show boundaries of your architecture as well as its integration into the rest of the system. Introduce the logical view with CRC cards, class diagrams, sequence diagrams. Don't come up with technology-centric issues too early. Even if you are using .NET Remoting and C# and SQL Server in your project, to name an example, your architecture baseline should not depend on these technologies, at least not its logical structure. Complete documentation using step-by-step refinement up to the deployment view.
• To ensure symmetry, always use the same diagrams for the same purpose such as UML diagrams, ER diagrams, or domain-specific languages (DSLs). Also make sure, that these diagrams use the same meta-model. For example, introduce project- or domain-specific stereotypes in a separate document (see first bullet).
• Add a glossary that explains all relevant terms and abbreviations. And make sure, all documents use the same terms with the same meanings.
• Add references to other documents that are relevant for reader understanding.
• Motivate all important design decisions that are not obvious. I've read so many documents that introduce architecture without presenting the rationale. Another software architect that reads your document must be able to understand the rationale (the "why" not just the "what"). Understanding the rationale also means understanding the architecture.
• For the same reason, always explain in your document how your architecture addresses the requirements. Thus, requirement traceability will be possible.
• Use patterns and explain the patterns used in the architecture document without providing full pattern descriptions. Rather refer to existing pattern descriptions in literature or special pattern documents.
• Structure the architecture documents in a tree-like hierarchy. The root is defined by the overall strategic architecture document that introduces the whole system. In the root document introduce all relevant subsystems as well as cross-cutting concerns such as security, scalability.
• The nodes right under the root then denote subsystem documents and further documents that address the most important cross-cutting concerns. If your subsystems consist of large entities themselves you may add additional leafs to the document hierarchy.
• Also specify testability (such as unit tests) in your document. This defines the specification of your architecture as well as how its implementation can be tested.
• Check-in all your documents in a configuration management system. Use versioning for your documents.
• Write the lead author or all co-authors onto the document cover page, so that a reader might track down the authors. Also specify date and version.
• Let other people review your document (and design). Feedback should be related to comprehensibility and technical soundness. Don't rely on the colleagues that are in the same subteam but also ask other people (managers, architects, testers) to read and review your documentation.
• A more process-related issue: make sure your architecture document always reflects the current state of the implementation (if already available). Otherwise, reading your document might be a complete waste of time and even cause other teams to draw wrong conclusions.
• Add diagrams and figures to explain your design, especially for complex architectural issues. No one will be capable of understanding hundreds of lines without any visualization. Drawing diagrams requires additional efforts but is always worth the time being spent.

These are some recommendations I have derived from my work as software architect. I am sure there is even more. If you find this helpful or if you have additional suggestions or feedback don't hesitate to add your comment.