The Value of Software Architecture Documenting Modern Web Development Projects
Long gone are the days of waterfall based software development at many companies. Waterfall projects were managed through a collection of established phases (conception, initiation, analysis, design, construction, testing, production/implementation, and maintenance) flowing in a downward progression like a waterfall.
This method of software development fell silent for two reasons. First, it is nearly impossible to discover the true project requirements in the early stages. The software development process was not prepared to respond to the changing needs of the stakeholders. Second, the phased approach was time consuming and could not keep pace with the project schedule. Each phase had a set of defined artifacts produced as part of the tollgate reviews. Volumes of documentation were created, reviewed, approved and grew stale.
Today most teams are using some form of agile principles to plan and execute their software development lifecycles (SDLC). These five meetings (release planning, sprint planning, daily scrum, sprint review, sprint retrospective) are the primary way teams work together. They use powerful tools to plan and execute these agile efforts. Pages of documentation have been reduced to stories and epics by the product owners and scum masters. Perhaps this is a good thing or perhaps we have lost something important in our attempts to be more agile.
The process of software architecture seems to be an afterthought in the modern SDLC. Developers just started working in their favorite editor or integrated developer environment (IDE). They create prototypes that grow into alpha, beta, and general availability (GA) releases. Somewhere between the product requirements documentation (PRD), the scrum stories, and the coding there should be time to design and document the underlying architecture in the best tools and methods.
The additional effort is not as great as you might think. The development team is already performing some level of design. They did not just start coding. The team probably wrote it down somewhere. Perhaps it can be found on a whiteboard, scratch paper, or even a bar napkin. It is only a bit more effort to capture these designs in a proper architectural language such as the Unified Modeling Language (UML).
Consider investing in proper architecture documentation when creating new products, adding major features to existing products, or executing significant refactoring projects in your legacy code. Here is an overview of the architectural dimensions necessary in any design.
4+1 Architectural View Model
Most architecture designs have some level of complexity on one or more dimension. Software architects use the 4+1 Achitectural View Model to isolate, design, and analyze these dimensions. Each of the 4 views focuses on a different architectural perspective.
The logical view allows the conceptual framework to be defined layer by layer each time drilling down deeper into the design. The logical view allows the architect to focus on the design without the constraints of physical requirements. It is important to start with the logical view. This is where the critical thinking is required to design properly at these levels. Break the project solution into sub-systems, modules, components, interfaces, object classes, and perhaps even major functions if appropriate.
The development view presents the developers' perspective and is concerned with software code management. The logical view of the software is translated into the actual software modules and organized into files and directories on the disk. This view is best represented with the UML component or package diagrams.
The process view addresses the dynamic aspects of the system and defines the system processes and how they communicate within the system. The process view examines concurrency, distribution, integrators, performance, and scalability. This view is best represented with the sequence and collaboration diagrams.
"Make time to design and document the underlying architecture of your web application".
The physical view depicts the system from an IT operations perspective and is concerned with the topology of software components on the physical layer, as well as the physical connections between these components. This view is best represented with the deployment diagram.
The scenarios dimension applies the major use cases as part of a fifth view. The scenarios describe the sequences of interactions between objects and across processes. This view is best represented with the use case diagram.
Parts of the Architecture Document
The next step is to organize the documentation into the proper sections. Start by working in a collaborative online tool. The documentation is more likely to stay current with Wiki based tools like Confluence. The wiki page can be organized as a traditional technical requirements document. The high level sections include Introduction, System Purpose, Structure, Dynamic Behavior, Map Other Views, and Conclusion.
The Introduction section should include the sub sections Team Members, Revision History, and Audience Definition. This section works best as a set of tables. The System Purpose section should include the subsections Context, System Interface, and Non-functional Requirements. As the names suggest this is the place for the UML Context diagram along with a description the diagram. The diagram highlights the key personas in the solution. The system Interface will inventory the possible combinations of scenarios based on the personas.
The Structure section should include the subsections Components and Interfaces. This should be the location for the component and interface diagrams. Use these two diagrams and the corresponding descriptions to define the Logic View Model. The Dynamic Behavior section should include the subsections Scenarios and Mechanisms. This is the best place for the Scenarios ViewModel and the Use Case diagram. The Other Views section should include the Process View, Development View, and the Physical View. Place the Sequence, Component, and Deployment diagrams in each of these three subsections.
I encourage you to rise to the occasion, to perform the critical thinking, and consider all of the views. Do not make architecture and documentation an afterthought. This is one of the key disciplines that enable development teams, commercial products, and companies to move beyond programming into the domain of commercial grade software engineering.