This document is able to quickly paint a picture of the entire system and its processes. — Scott Wilson
A functional application is always the highest priority and that always leaves documentation artifacts at risk for potentially never getting completed. However, this behavior can be a serious impact to the efficiency and effectiveness of anyone that supports the application going forward. It is most obvious when someone new joins the team or someone rejoins the team after time has passed.
One of the most efficient ways to reduce this risk is by including and maintaining current architect diagrams within the repo. This allows anyone the ability to quickly see the various components, environments and processes. We have standardized on the usage of the The 4+1 architectural view model as the base for our architecture diagrams. It enables everyone to quickly and easily see the application from the following viewpoints:
- Logical view – uses class diagrams and state diagrams to describe and illustrate an end users view of the system.
- Process view – uses activity diagrams to describe and illustrate the flow of the application processes as it interacts with the various components of the system.
- Development view – uses component diagrams and package diagrams to provide the developer with an implementation view.
- Physical view – uses deployment diagrams to provide the engineer with a deployment view.
- Scenarios – uses use cases (and is even referred to as the use case view) to describe and illustrate the interactions between processes and objects.
We have found it so beneficial that it has become a requirement for all of our applications and have even created multiple 4+1 diagrams for specific phases and layers of more complex systems. We recommend that you standardize the location of these diagrams within your repo as well, so that everyone knows where to quickly find them. We use /docs.
Here is an excellent example of a full 4+1 Architectural Blueprint diagram for a Microsoft-Platform DevOps Environment created by Jeffrey Palermo.
References
- Wikipedia: 4+1 architectural view model, Class diagram, State diagram, Activity diagram, Component diagram, Package diagram, Deployment diagram, Use case
- Architectural Blueprints – The “4+1” View Model of Software Architecture by Philippe Kruchten, Rational Software Corp
- Microsoft-Platform DevOps Environment 4+1 Architecture Blueprints created by Jeffrey Palermo