Documenting software architecture is an essential part of software development. It helps to ensure that the software is well-understood, thoughtfully designed, and can be communicated to others. In this blog post, we will discuss how to create a well-designed Enterprise Architect model documenting the whole software architecture of a given system.
Firstly, it is important to understand what an Enterprise Architect model is. An Enterprise Architect model is a diagram created using available standards, in which the primary aim is to illustrate a specific set of tradeoffs inherent in the structure and design of a system or ecosystem 1. Software architects use architectural models to communicate with others and seek peer feedback 1.
To create a well-designed Enterprise Architect model documenting the whole software architecture of a given system, it is important to document important issues, possible solutions, and reasons for choosing one of the solutions 2. There are various reasons to document decisions in the project lifecycle, such as:
- Reasoning that stood behind a choice will blur with time so the architect will not be able to precisely discuss or defend the choices or evaluate if the decisions made are still valid.
- Architect may need to describe reasons for his decisions for various reasons like some other architect joining the team or client (or consultancy company hired by client) having some questions about the design.
- Requirements and constraints may change in time and decisions may have to be reviewed. Knowledge about the full context behind decisions made is fundamental in reviewing them.
- Architect may choose to leave the project or for some other reason, another architect may have to take over the responsibilities of the architect who originally made the decisions.
- Building a database of architectural patterns and decision will allow the company to learn with every project, instead of relying on the memory of individuals 2.
It is also important to remember that software architecture documentation is not a replacement for low-level design documentation (if such is provided in the project) or documenting code 2. Documentation must be lean and contain enough information to be helpful 2. A very good analysis is available in Sustainable Architectural Design Decisions 2 article, and you can also find many blog posts or discussions on this subject on forums and social media portals.
In conclusion, documenting software architecture is an essential part of software development. To create a well-designed Enterprise Architect model documenting the whole software architecture of a given system, it is important to document important issues, possible solutions, and reasons for choosing one of the solutions. Documentation must be lean and contain enough information to be helpful. Building a database of architectural patterns and decision will allow the company to learn with every project, instead of relying on the memory of individuals. Remember that software architecture documentation is not a replacement for low-level design documentation (if such is provided in the project) or documenting code.
