See also question A-5 (target audience of architecture documentation).
- Short answer
-
You need to inquire with your specific stakeholders, we can only give you rough approximations from our experience… that will most likely miss the goals of people involved in or with your system.
Show them examples what you could deliver with low effort. Incorporate their feedback. See #tip-iii-3 (appropriateness).
Longer answer
Read the short answer above! Ask your specific stakeholders, what artifacts or information they expect or require from the architecture documentation (or more general, the technical documentation).
Don’t ask what they require from the system (hopefully you already know that…)
Typical answers we received are summarized in the following table:
Stakeholder | Required information/artifacts |
---|---|
Project management | Quality goals, (business) context with external interfaces, solution strategy (most important architectural decisions), building block view level-1, overview of important concepts. Sometimes an overview of infrastructure and deployment. |
Top- or upper management | Top-3 quality goals, major business requirements, business context with neighbor systems, compliance to IT strategy, compliance to security (and maybe other) standards, operation/deployment concepts, cost-relevant architectural decisions. |
Product owner | Quality goals, building block view with interfaces, overview of important architectural decisions, overview of crosscutting concepts, known issues and risks |
Software developers | Quality goals with detailed scenarios, solution strategy with links to detailed concept descriptions and/or example solutions, building block view with interface descriptions, important runtime scenarios, domain model, crosscutting concepts, deployment view with possible variants, glossary. |
Operators, administrators | Infrastructure and deployment, external interfaces with technical and organizational details, logging and monitoring concepts. |
Tester, QS-team | Detailed business and quality requirements, solution strategy, building blocks with interfaces, crosscutting concepts influencing testing or testability. |
Developers of neighbor systems | Business and/or technical context, details description of external interfaces, end-to-end interaction/runtime scenarios at these interfaces. |