What should you include in software architecture documentation?

1 Purpose and scope

The first thing you should include in your software architecture documentation is the purpose and scope of the system. This section should answer questions such as: What is the problem that the system solves? Who are the intended users and customers? What are the functional and non-functional requirements? What are the assumptions and constraints? What are the scope and boundaries of the system? This section should provide a clear and concise overview of the system's context, objectives, and expectations.

2 Architectural views

The next thing you should include in your software architecture documentation is the architectural views of the system. These are different perspectives or representations of the system that highlight its key aspects and concerns. For example, you can use a logical view to show the main components and their responsibilities, a physical view to show the deployment and distribution of the system, a process view to show the concurrency and communication of the system, and a scenario view to show how the system behaves in specific situations. You can use different notations and diagrams to illustrate these views, such as UML, ERD, or BPMN.

4 Architectural patterns and styles

The fourth thing you should include in your software architecture documentation is the architectural patterns and styles that you applied or followed in your design. These are reusable solutions or guidelines that address common problems or challenges in software architecture. For example, you can use a layered pattern to separate the system into different levels of abstraction, a client-server style to enable distributed communication, a microservices style to enable independent deployment and scalability, or a MVC style to separate the presentation, logic, and data of the system. You should describe how these patterns and styles fit your system's needs and goals, and how they influence its structure and behavior.

5 Architectural principles and standards

The fifth thing you should include in your software architecture documentation is the architectural principles and standards that you adopted or defined in your design. These are the rules or conventions that govern the system's architecture and ensure its consistency, quality, and maintainability. For example, you can use principles such as modularity, cohesion, coupling, abstraction, or encapsulation to guide your design decisions and improve your system's modularity, cohesion, coupling, abstraction, or encapsulation. You can also use standards such as naming, coding, testing, or documentation to ensure your system's readability, reliability, or traceability.

6 Architectural evaluation

The sixth and final thing you should include in your software architecture documentation is the architectural evaluation of your system. This is the process of verifying and validating your system's architecture and ensuring that it meets its requirements and expectations. You can use different methods and techniques to evaluate your system's architecture, such as reviews, inspections, audits, testing, analysis, or simulation. You should document the results and feedback of your evaluation, as well as any issues, defects, or improvements that you identified or implemented.

7 Here’s what else to consider

This is a space to share examples, stories, or insights that don’t fit into any of the previous sections. What else would you like to add?