Documenting application architecture is an important part of the software development process. Paulo Merson recently talked about the role of documenting architecture in managing the Reference Architecture (RA). He did a presentation at SD Best Practices Conference on what information about an architecture should be captured and how UML 2.0, BPMN and other modeling notations and guidelines can be used for architecture representation.
The task of documenting the application architecture helps the architects and developers to evaluate the architecture and use it to guide the implementation (design and code).
Architecture can be described using Views (also known as Viewpoints or Perspectives) which are the representation of a set of system elements and the relations associated with them. A view constrains the types of elements and the types of relations that can be represented in that view. An architect can consider the system in a Multi-View Architecture based on:
- How the system is structured as a set of code units (Module Views)
- How it is structured as a set of elements that have runtime presence (Runtime Views)
- How the artifacts are organized in the file system and how is the system deployed to hardware (Deployment Views), and
- The structure of the data repository (Data Model)
Module Views:
These views show the structure of the system in terms of units of implementation (modules and the relations among these modules. Module Views act as the blueprints for the code. They can be used for budgeting, work assignment and tracking, and modifiability and impact analysis purposes. They are also useful for the education of new developers.
Runtime Views:
Also known as component-and-connector views, they show the structure of the system when it's executing. These views include elements like components that have runtime presence (e.g., processes, threads, EJBs, Servlets, DLLs, objects, ASP.NET components), data stores, and complex connectors (e.g., queues, pipes). They also show the interaction mechanisms, which vary based on technology, but should at least distinguish local from remote calls and synchronous from asynchronous invocation. Runtime Views show how components interact at runtime, what components are replicated, and what components access data stores. They can also be used for the analysis of runtime properties such as performance, security, and reliability.
Deployment Views:
These views are typically used to describe the hardware infrastructure of the production environment and the structure of directories and files of the deployed system. Deployment Views are useful for defining deployment and operation procedures (like "automatic updates" feature), auditing runtime failures and planning purchasing options.
Data Model:
It shows the structure of the data repository which includes data entities (persisted domain elements) and the relationships between these entities. Data models can be used as a blueprint for the physical database and are a useful reference for developers of data access code. They can also be used to assess performance in data-centric systems by analyzing the data elements like indexes and locks, SQL optimization, modifiability impact analysis, and input to normalization activity.
Paulo also stressed the importance of documenting behavior of the system. Behavioral documentation complements structural diagrams. He talked about the modeling notations used in UML diagrams such as Sequence, Communication (formerly called Collaboration diagrams in UML 1.x), Activity, and State Machine diagrams (formerly called Statechart diagrams). There are other notations like BPMN can be used to document the behavior of the system.
He discussed a template for documenting the software architecture views:
- Primary Presentation:
Diagram showing the elements and relationships among them. - Element Catalog:
Explains elements depicted in the primary presentation and is usually a table with element name and textual description. It may contain interface specifications as well as behavior documentation. - Context Diagram:
Shows what's in and what's out of the system (or the part of the system the view is focusing on) - Variability Guide:
Describes the variability mechanisms, such as replication of components and connectors, optional inclusion of components and connectors, selection among different implementations of a component and parameterized values (build-time flags, config files, etc.). In this section, the items that can vary, the effect of the variation and the binding time (compile, build, deploy, or run time) should be documented. - Architecture Background:
This section should include rationale for design decisions (including relevant rejected alternatives), results of analysis, prototypes and experiments, assumptions and constraints affecting this view, and known patterns used in the design. - Related Views:
Pointer to parent view or children views
Paulo suggested the outline of a Software Architecture Document should include the following sections:
- Documentation Roadmap:
The roadmap should show how documentation is organized and should have a reference to the template used and include scenarios for using the documentation. - System Overview:
This section should include the description of the system and its purpose. It may point to the system overview elsewhere in the overall system documentation. - Requirements:
This should include the requirements of the system. It may point to a separate requirements document. Three kinds of requirements are relevant to the architecture: functional requirements (can be captured as use cases or user stories), quality attribute requirements (performance, availability, etc.), and design constraints. - Views:
This should include all the views that represent the software architecture. - Mapping Between Views:
This section shows how elements in one view map to elements in another view for selected pairs of views. - Architecture Analysis and Rationale:
Rationale for cross-view design decisions (including rejected alternatives), results of architecture evaluation (e.g., ATAM report) - Mapping Requirements to Architecture:
Shows how each requirement is satisfied by one or more elements of the architecture, or an architectural approach
The document should include a Glossary and Acronym List in the document. Paulo showed some example model diagrams he created for Duke's Bank application and other design diagrams from real systems.
Concluding the talk, he discussed other important aspects of documenting the application architecture like the stakeholders' needs, reference architectures, and document variability in product line architectures (PLA). Paulo also said that other efforts like refining and refactoring the architecture as well as some type of architecture enforcement during software development and implementation phases are important to a successful architecture.
InfoQ spoke with Paulo about the current state and future direction of documenting software architecture.
How do UML Profiles and Stereotypes help in the efforts of documenting software architecture?
UML was initially created for modeling OO systems. It's now used for modeling any kind of software system. That means it's generic and hence has to be very flexible. UML stereotypes are a UML extension mechanism that allow assigning specific meaning to UML symbols. The stereotypes allow you to create more expressive diagrams. Let's say you have a (generic UML) connector in a diagram. If you know that connector is actually a JMS queue, you can stereotype the connector as <<JMS queue>>. You can put a set of stereotypes that make sense together in a UML profile. The UML specification has as an annex a profile for Java EE, a profile for .NET and a few others. It's a good idea to reuse or create your own stereotypes and profiles.
With several software development teams using Agile methodologies now-a-days, what can the software architects do to be Agile and pragmatic in documenting the application architectures?
It is a well known misconception that agile development means no documentation. In fact, as a survey shows, agile teams are more likely to model than traditional teams. A few things that agile architects (or perhaps any software architect) should remember:
The key aspect of design/modeling in agile projects is not to avoid designing, but to avoid "big-design up-front" (BDUF). In general, high-level architectural strategies should be worked out up front, but many design decisions and design details can be left to when you need them.
Only produce design documentation that will fulfill a need of the stakeholders. Stop designing as soon as you're ready to start coding. In the next sprint you can expand/refine the existing design as needed in order to capture design decisions required by next sprint's features.
If it's not worth updating the design, throw it away. Some design diagrams are used to guide implementation, but at the end the code sometimes looks different from the diagram. If you don't have time to update the diagram to reflect the implementation, it's better to remove it than keeping an out-of-date diagram that may confuse a future reader.
Many times, sketches are all you need. Don't spend too much time crafting the neatest diagram using the latest and richest notation available. Don't spend too much money on sophisticated modeling tools if you just need a drawing tool. In many agile projects, especially the ones with small, co-located teams, the true value of design diagrams comes from drawing them, which forces you to think through the issues; once the issues are solved, the diagrams lose much of their value. Many times the design is represented as a sketch on a whiteboard or piece of paper. If the sketch can be used to successfully convey the design to the team, that sketch, as is, can be *the* diagram your architecture view. Why not?
Is there anything special in documenting the architecture of an SOA system?
SOA typically involves many design decisions (SOAP vs REST, ESB or direct point-to-point, service granularity, use a directory or not, use BPEL or not, SSL or message-level security, and many more). Each design decision has multiple alternatives. So it's important to understand and record the rationale for the choices you make. There are other considerations in Section 3.3 of a report we wrote last year called "Evaluating a Service-Oriented Architecture".
What do you see as the future of Software Architecture Documentation?
The software architecture discipline is far from maturity. There are great software architects out there creating ingenious solutions every day, but they work in different ways, they create different artifacts and use different notations for diagrams. A vision I like for the future is that new architects learn the craft at school rather than try-and-error in the battlefield. Part of this education is proper ways to represent the software architecture for other people's consumption. Important initiatives in the direction of good software architecture education are: the work of Grady Booch on the handbook of software architecture and the publications and curriculum developed at the SEI.
What do you recommend to the architects as the best practices and "gotchas" in the area of documenting Software Architectures?
- Document the architecture in multiple views.
- Always have a notation key for your diagrams.
- If you're using a design/architectural pattern, let the reader know.
- Follow a template.
- Only create documentation that will be useful to some stakeholders.
- Documentation doesn't mean paper or Word documents. Think wikis for example.
- Record the rationale for important design decisions.
- Review what you create.
