Sufficiently documenting software design, including source code, is essential. But sufficiently documenting fundamental software architecture views is critical. There are many views to consider during design and analysis of a system. This time a basic deployment view is discussed.
A simplified deployment view is a high level tangible mapping between system elements (e.g. messaging queue) and physical hardware spread across network topography.
One of SoftwareArchitectures.com colleagues, PJ, observed the following situation at his current client engagement.
The task of overseeing the deployment of a significant iterative release into the test environment was assigned to the associate architect of a system. The client’s environment features institutionalized configuration management policies that can be circumvented when pushed, but the deployment manager has no access the system directly. The test environment administrator, who physically controls the test environment, is only available by phone and email.
The build and deployment process went smoothly across most of the tiers of the test environment with the exception of the application tier. Specifically the configuration of the messaging framework and the business logic residing in this tier was not deployed successfully.
Having no access to the environment where an unstable release is being deployed is challenging. What made this situation dire is lack of usable deployment documentation. Yes, there were some back and forth emails containing information about various machines across environments, but none of the information could be readily used as a reference. This ultimately resulted in the following fundamental problem: people involved in the process of configuring and troubleshooting the environment did not have a shared view of the solution. The deployment timeframe stretched from that afternoon to late evening and then extended onto the next few days and eventually weeks until full smoke test could be run.
In an ad hoc environment, no matter how big or small, it is the responsibility of the architect to always have a readily available deployment view in the back of his pocket.
Software architects and designers may feel lax when it comes to recording decisions on the daily basis: a conscious and a well thought design may materialize with little documentation overtime. Not surprisingly the deployment view is the last thing that comes to mind in a deadline oriented ad hoc environment. But it’s the deployment view that represents architect’s view of a target environment and lubricates communication channels between the design and development team and the colleagues who manage the test environment. Like a fire escape plan on the door of a hotel room a basic deployment view must show the components of a system being deployed specific to the target environment.