The book Documenting Software Architectures: Views and Beyond, 2nd Edition covers the software architecture documentation and how to express an architecture so that the developers can develop and maintain a system from it. The book covers different architectural styles like service-oriented architectures (SOA), multi-tier architectures, and data models. The discussion also includes reference guides for three architecture documentation languages: Unified Modeling Language (UML), Architecture Analysis and Design Language (AADL), and Systems Modeling Language (SySML).
InfoQ spoke with Paulo Merson, co-author of the book on software architecture documentation concept and how it can be used to model the architecture to help with the design and development of software applications.
InfoQ: What was the main motivation for writing the 2nd edition of the book?
Paulo Merson: Based on the 1st edition, published in 2002, we developed a 2-day course on Documenting Software Architectures. We have taught this course to thousands of students. We have also helped several organizations to document and evaluate their architectures. In this process we identified several points to improve in the first edition, more than enough to prompt the authors to write the 2nd edition. In addition, we needed to update the book to use UML 2 and to show examples covering more recent technologies.
InfoQ: What new content has been added in the new edition compared to the first edition?
Paulo Merson: There is a lot of new content in the second edition, including:
- New architectural styles, such as SOA and multi-tier.
- Architecture views to describe the installation and deployment structures.
- Data model as an architecture view.
- Use of aspect-oriented modules in the design.
- Better coverage of behavioral diagrams, such as UML sequence diagrams, activity diagrams, and state machine diagrams.
- How to review an architecture document.
- Documenting the architecture in an Agile context.
- Collaboratively recording documentation in a wiki.
- An appendix that describes how to use the UML notation to capture different views of the architecture.
- How to document the reasoning behind important design decisions.
We also revised the different templates for architecture documentation suggested in the book, and replaced all but a few of the examples used in the book. There is also a new example of a complete software architecture document, which we made available online in a wiki.
InfoQ: Who is the target audience for this book?
Paulo Merson: The primary audience consists of software architects. But the Documenting Software Architectures (DSA) book is enormously helpful to all software developers, because we (I’m myself a developer in industry) think, discuss, and implement pieces of software design all the time.
One of the merits of the book is to lead the architect to cater to the interests of a wide group of stakeholders of the architecture, including people outside the development team. So, even though I don’t expect, for example, network administrators to read the book, I’m sure they’ll benefit from it when the software architect realizes they are also interested in parts of the architecture—the book tells which parts and how to document them.
InfoQ: What are some metrics that architects (especially those working in Agile and Lean software development environments) can use to ensure that the time and effort they are spending in documenting Software Architecture is really adding business and architectural value?
Paulo Merson: This is an important question. Replace “in documenting software architecture” in this question with “in applying TDD”, “in doing continuous integration”, “in performing peer reviews”, or other software development recommended practice. A web search shows that calculating the value (or “return on investment”, “cost-benefit”) of these good practices to real projects is something that very few organizations actually do. Nevertheless, in the book we present a formula to calculate how much you save by creating good architecture documentation (AD):
∑ over every activity A in the project (cost_of_A_without_AD - cost_of_A_with_AD) > cost_of_AD
The formula is simple, measuring the values is not. An ongoing research project at the SEI is trying to measure the impact of introducing architecture documentation to a large open-source software project. I hope a year from now there’ll be public, quantified empirical evidence of the value added by sound architecture documentation. But in the book we emphasize the importance of documenting only what’s necessary to the stakeholders. We suggest things that may reduce the cost of the architecture documentation without compromising quality. Some of the suggestions are: discarding diagrams that are no longer helpful and became out-of-date, using a wiki, using templates for the documentation but filling in only the sections required by someone to do their job.
On the other hand, it’s easy to find anecdotal evidence that the lack of good, up-to-date architecture documentation can cost a lot. Like me, I’m sure many people reading this can think of experiences they’ve been through.
InfoQ: What are the emerging trends and techniques in software architecture in general and documenting software architecture in particular?
Paulo Merson: Architects must be attentive to new frameworks, technologies, languages, tools, and patterns that can be used in the kinds of software systems they design. Keeping up with these new things is hard (though fun). The architect must know not only how these things are used but also the implications in terms of performance, security, reliability, modifiability, testability, etc. As for trends in the task of creating and documenting software architectures in general, there’s less to keep up with. There are, for example, model-driven and/or domain-specific modeling tools that can generate code for you; there are powerful IDEs with integrated design plug-ins that allow you to model and code (or reverse engineer the code and model) in sync; there are formal architecture description languages and respective tools that can analyze your design with respect to different properties. Although these solutions are immensely welcome in specific projects, they’re seen as “sustaining” innovations by many people designing software out there, who can get their designs across with just sketches on the whiteboard.
Software projects that have distributed teams are a trend. They bring new challenges for communicating the design. I have had successful experiences with wikis as a media for architecture documentation and using desktop sharing tools in teleconferences. Another trend is the use of tools that can analyze the code and design artifacts to gauge certain qualities, such as level of coupling (which affects modifiability). Some tools can look at code changes and generate measures over time to detect and help prevent degradation of the code, which is a natural phenomenon caused by the high turnover of developers and lack of understanding and enforcement of the original design.
InfoQ: Documenting Software Architecture helps with modeling the domain. What are your recommendations to validate and ensure that the implementation (code) is in alignment with the model (architecture)?
Paulo Merson: To ensure that the code conforms to the intended architecture the most important thing is to make sure the architecture is effectively communicated to the people writing the code. Architects should have strong coding skills. They should also be fully aware of what developers need to know about the design and what modeling notations are they familiar with. Architects should then document the design in multiple views in an organized, non ambiguous and objective way, making sure to cover structural and behavior information, software interfaces and rationale for design decisions. The DSA book tells the whole story about creating effective architecture documentation.
Once code is in place, something that is very helpful (and feasible!) is to use static analysis tools to verify that the code doesn’t violate the intended architecture. For example, in a layered design, the tool can check whether usage dependencies from a lower to an upper layer are present in the code. Detecting lack of conformance between code and architecture is the first step. The much harder next step is to fix the violations found. If not fixed, these violations tend to proliferate due to “copy and paste reuse”. But there’s a better alternative to detecting and fixing violations. In a recent project, we configured these kinds of conformance checks to run automatically before any commit to the code repository, preventing violations at the source.
InfoQ: What role can efforts like documenting Software Architecture play in defining and executing Enterprise Architecture (EA) processes that are using frameworks like TOGAF?
Paulo Merson: Architecture frameworks like TOGAF, DODAF, and MODAF prescribe sets of views (also called viewpoints or models). These views are somewhat generic because the architecture frameworks are not specific to one organization, domain, or technology. The DSA book can certainly help you to create architecture documentation that corresponds to several of the prescribed views in these architecture frameworks. But our book is focused on software, more specifically, the architecture of software-intensive systems, and we get to the gist of it. Enterprise architecture is a concept that includes but goes beyond software systems.
InfoQ: Techniques like Domain-Driven Design (DDD) and Domain Specific Languages (DSL)help with defining and implementing the business domains. How do these approaches fit with software architecture documentation efforts?
Paulo Merson: Documenting the software architecture involves describing the different structures that form a software system. One kind of structure shows the implementation units. In the book we show how module views document this kind of structure. A DSL is a clever mechanism that makes implementation and maintenance easier. The use of a DSL should transpire in the module views of the architecture. For example, suppose you developed a DSL to codify the rules for validating different kinds of data records submitted via variations of a basic web form. Thanks to that DSL, new variations of the web form can be quickly added to the system. The DSL impacts modifiability and reuse. You may not need to explain your DSL in the architecture documentation, but in the module view that describes the modules that handle the web forms input you should indicate (even if just as a comment box in a diagram) where the DSL is used. Recording the rationale for using a DSL and the DSL design is also important. DSLs are often used to achieve variability, which is “built-in” flexibility that is added to the system design and implementation.
DDD is a celebrated technique for building object-oriented software systems by focusing on the domain objects. It prescribes a set of design patterns for organizing the implementation units. From an architecture documentation standpoint, the main benefit of DDD is introducing a vocabulary of terms that have specific meaning in the design. For example, if you point to a DDD practitioner a region of a design diagram and say that region forms a bounded context, the information is clear to him. Thus, you can more easily communicate your architecture in terms of bounded contexts, modules, entities, factories, aggregates, and other terms used in DDD. But if you’re following DDD, it’s important that the whole team is familiar with it in order to enjoy that benefit. I believe DDD enthusiasts will resonate with and greatly benefit from our DSA book, which shows a variety of ways to effectively communicate layered designs, state machines and trace-based behavior, interaction among runtime elements (e.g., threads, processes, databases), the structure of deployment elements, interface specifications, and more.
Paulo also talked about the importance of communicating the software architecture to other team members like developers. He said:
If you create the best software architecture in your head but fail to communicate it to the developers and other stakeholders, what is that architecture worth? As we say in the preface of the book, designing an architecture without documenting it is like winking at a girl in the dark. You know what you’re doing, but nobody else does.
As I wrote in a recent blog post, lack of good architecture documentation may be OK in some cases, but becomes a problem when the design has to be communicated across time (to a developer who will join the team six months later) or space (to a developer working in another country). I have been part of many software projects of various kinds and very rarely I found clear, succinct and unambiguous design documentation. Many times the code is the only reliable documentation. The purpose of our book is to answer the following question: How do you document an architecture so that others can successfully use it, maintain it, and build a system from it? Understanding what to document and how to document in each case takes experience, but our book is the definitive fast track to master that skill.
When we talk to people about software architecture and what pieces of information it should contain, a very common request is for a good example of architecture documentation. In my opinion one of the main contributions of this book is to make available an example that shows different architecture views, behavior documentation, interface documentation, rationale discussion, and much more.
The book, “Documenting Software Architectures: Views and Beyond”, 2nd Ed., is authored by Paul Clements, Felix Bachmann, Len Bass, David Garlan, James Ivers, Reed Little, Paulo Merson, Robert Nord, and Judith Stafford, published by Pearson/Addison-Wesley Professional, Oct. 2010, as part of the SEI Series in Software Engineering, Copyright 2011 Pearson Education, Inc. For more information about the book, please visit this website.
About the Book Author
Paulo Merson has 20 years of software development experience. He’s a visiting scientist with the Software Engineering Institute (SEI) at Carnegie Mellon University, where he works with software architecture and SOA. Paulo also works in industry as a software architect. His speaking experience includes tutorials at SD Best Practices, Dr. Dobb’s Architecture & Design World, JavaOne, SATURN conference, lectures to graduate students in different universities in the US, Europe and Brazil, and invited talks at different companies. Over 20+ years, he has actively participated in different roles in the development of software products for different domains and using different technologies. He is co-author of Documenting Software Architectures: Views and Beyond, 2nd edition. Paulo holds a BSc in Computer Science from University of Brasilia, and a Master of Software Engineering from Carnegie Mellon.