An Interview with Paul Clements on Documenting Software Architectures
Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
John Morley: Why did you create a second edition?
Paul Clements: We thought that the message of the first edition was really strong, but that it was becoming technologically outdated. For example, in the first edition we relied on an outdated version of the Unified Modeling Language (UML) to make many points. We tried very hard to make the book notation-independent but not notation-free. Since UML is the de facto standard for architecture documentation, we needed to have an edition available that uses the current version of UML. But there were many other things we added and updated as well.
John: What else is new in this edition?
Paul: We introduced several architectural styles into the book that have come into widespread use since the first edition, especially service-oriented architectures. We also treat the architecture-level documentation of a software system’s data model. We also cover aspect orientation, and the system’s installation and production environments as architectural styles.
We’ve added a new chapter about reviewing an architecture document to make sure it’s serving its stakeholders as intended.
This edition is much more Agile-friendly, orienting its advice to be consistent with the Agile Manifesto’s entreaty to value working software over comprehensive documentation. We talk about using new ways to capture architecture, from wikis to whiteboards.
We added three appendices about languages for architecture: UML, SysML (Systems Modeling Language), and AADL (the Architecture Analysis and Design Language). These appendices form mini reference guides from an architectural perspective.
Years of use and feedback led us to make several improvements in the suggested templates for architecture documentation. The templates are also more flexible, and we lay out different options for arranging documentation. And we have a whole new section on documenting the rationale behind architectural decisions.
We updated the comprehensive example of a documented architecture. It will resonate with more people; it’s a web-based, service-oriented system, more in today’s industrial mainstream. To make the book smaller and allow us to maintain the example over time, we put it online.
And, as I mentioned, since the first edition was published, the UML has graduated to version 2.0 and beyond. That opened up new possibilities for more documenting various architecture constructs in a more straightforward way, especially components and connectors. Where necessary, our figures are updated to reflect the new constructs.
John: What is the significance of the bird’s wing on the cover of this book?
Paul: When people talk about architecture, they typically use a metaphor of building architecture, rooms and hallways. I think physiological systems are a much better metaphor for systems and software architectures. Buildings certainly have architectures, but buildings, for the most part, just sit there and don’t do anything. In a bird’s wing, there are bone structures, nerve structures, circulatory structures, and so on. Feathers are replicated complex substructures, but no two are exactly alike. You build a lot of systems that way. What’s fantastic about a bird’s wing is that when you put all those structures together you get astonishing behavior with incredible quality attributes.
John: In the book’s preface, you write that the purpose of the book is to answer the question, "How do you document an architecture so that others can successfully use it, maintain it, and build a system from it?" Why is that important?
Paul: There’s a quote from Thucydides that goes something like this: If you have a good idea, but you don’t have the facility to express it, you might as well not have had it. An uncommunicated architecture is a useless architecture. You might as well have not bothered, and had your architects sweep the halls or empty the trash. Communicating the architecture is the crowning achievement after creating it.
John: You also write that “we believe what an architect really needs is guidance in which architecture and its stakeholders are the first-class citizens, and language is relegated more appropriately to a supporting role. That’s what we’ve tried to provide with this book.” Why do you think that?
Paul: Language often constrains thought and influences the way we think about problems. We tried to write a book that was first about the things you want to express, and second about how to express those things in various available notations. In many cases, we say “Instead of creating a UML diagram, you might want to just make a table or write an ordered list.”
What do you want to say about an architecture, so that other people can use it? You want to talk about architectural elements, the relationships among elements, the properties of elements, the behavior of elements in concert with one another, and the interfaces the elements provide in order to interact with one another. All of those are first-class citizens in documentation.
Once you know the important stuff to say, then you can talk about how to express it in the notation of your choice. There are a ton of books on UML, SysML, and others. We think those books take a more parochial view than we want to take.
John: If there could be just one thing you want people to know about this book, what would it be?
Paul: We made a conscious effort to make sure that a reader will never open the book and see just two pages of solid text. We tried to make the book visually appealing, and the layout of the book is crafted to do that.
We’ve put in over 200 figures and a couple of dozen tables. There are lots of illustrated examples of architecture diagrams in various notations. Here’s how you show a uses view, here’s how you show a service-oriented view, here’s how you show an install view, and so forth. Every page has something visual on it, such as notes in the margins to point people to more information, give definition of terms, and give quotes that provide context. At the very least on a page there is a bulleted list of important points. There isn’t a single page with just pure text.
For information on the software engineering course based on this book, please visit http://www.sei.cmu.edu/training/p33.cfm.