What do you think?
Rate this book
Documenting Software Architectures: Views and Beyond
Software architecture—the conceptual glue that holds every phase of a project together for its many stakeholders—is widely recognized as a critical element in modern software development. Practitioners have increasingly discovered that close attention to a software system’s architecture pays valuable dividends. Without an architecture that is appropriate for the problem being solved, a project will stumble along or, most likely, fail. Even with a superb architecture, if that architecture is not well understood or well communicated the project is unlikely to succeed.
Documenting Software Architectures, Second Edition, provides the most complete and current guidance, independent of language or notation, on how to capture an architecture in a commonly understandable form. Drawing on their extensive experience, the authors first help you decide what information to document, and then, with guidelines and examples (in various notations, including UML), show you how to express an architecture so that others can successfully build, use, and maintain a system from it. The book features rules for sound documentation, the goals and strategies of documentation, architectural views and styles, documentation for software interfaces and software behavior, and templates for capturing and organizing information to generate a coherent package. New and improved in this second edition:
Coverage of architectural styles such as service-oriented architectures, multi-tier architectures, and data models
Guidance for documentation in an Agile development environment
Deeper treatment of documentation of rationale, reflecting best industrial practices
Improved templates, reflecting years of use and feedback, and more documentation layout options
A new, comprehensive example (available online), featuring documentation of a Web-based service-oriented system
Reference guides for three important architecture documentation languages: UML, AADL, and SySML
“This new edition is brighter, shinier, more complete, more pragmatic, more focused than the previous one, and I wouldn’t have thought it possible to improve on the original. As the field of software architecture has grown over these past decades, there is much more to be said, much more that we know, and much more that we can reflect upon of what’s worked and what hasn’t—and the authors here do all that, and more.”
—From the Foreword by Grady Booch, IBM Fellow
Documenting Software Architectures, Second Edition, provides the most complete and current guidance, independent of language or notation, on how to capture an architecture in a commonly understandable form. Drawing on their extensive experience, the authors first help you decide what information to document, and then, with guidelines and examples (in various notations, including UML), show you how to express an architecture so that others can successfully build, use, and maintain a system from it. The book features rules for sound documentation, the goals and strategies of documentation, architectural views and styles, documentation for software interfaces and software behavior, and templates for capturing and organizing information to generate a coherent package. New and improved in this second edition:
Coverage of architectural styles such as service-oriented architectures, multi-tier architectures, and data models
Guidance for documentation in an Agile development environment
Deeper treatment of documentation of rationale, reflecting best industrial practices
Improved templates, reflecting years of use and feedback, and more documentation layout options
A new, comprehensive example (available online), featuring documentation of a Web-based service-oriented system
Reference guides for three important architecture documentation languages: UML, AADL, and SySML
“This new edition is brighter, shinier, more complete, more pragmatic, more focused than the previous one, and I wouldn’t have thought it possible to improve on the original. As the field of software architecture has grown over these past decades, there is much more to be said, much more that we know, and much more that we can reflect upon of what’s worked and what hasn’t—and the authors here do all that, and more.”
—From the Foreword by Grady Booch, IBM Fellow
592 pages, Hardcover
First published September 26, 2002
78 people are currently reading
699 people want to read
Ratings & Reviews
Friends & Following
Create a free account to discover what your friends think of this book!
Community Reviews
Displaying 1 - 13 of 13 reviews
September 20, 2015
All software projects have architecture, but not all have formal Architecture. This is a book for projects of the latter sort. Although the text had gems scattered throughout, much of what was presented was much too formal for the more agile and informal environment I work.
My recommendation is that most people will get the most value by skimming the prologue, especially sections P.2.2 and uses and audiences for architecture documentation, section P.4 on architecture styles, and P.5 on rules for sound documentation[1]. Flip through the chapters on the different view types and read the description of those that feel most relevant (skip the text about the examples and just look at the diagrams). Read chapter 7 on documenting software interfaces. Skim chapter 8 on documenting behavior. Read chapter 11 on reviewing an architecture document.
You won't find all of the gems this way, but you'll get a better value for your time investment than if you were to read the whole thing.
[1] In sum:
1. Write documentation from the reader's point of view
2. Avoid unnecessary repetition
3. Avoid ambiguity
4. Use a standard organization
5. Record rationale
6. Keep documentation current but not too current
7. Review documentation for fitness of purpose.
My recommendation is that most people will get the most value by skimming the prologue, especially sections P.2.2 and uses and audiences for architecture documentation, section P.4 on architecture styles, and P.5 on rules for sound documentation[1]. Flip through the chapters on the different view types and read the description of those that feel most relevant (skip the text about the examples and just look at the diagrams). Read chapter 7 on documenting software interfaces. Skim chapter 8 on documenting behavior. Read chapter 11 on reviewing an architecture document.
You won't find all of the gems this way, but you'll get a better value for your time investment than if you were to read the whole thing.
[1] In sum:
1. Write documentation from the reader's point of view
2. Avoid unnecessary repetition
3. Avoid ambiguity
4. Use a standard organization
5. Record rationale
6. Keep documentation current but not too current
7. Review documentation for fitness of purpose.
January 5, 2019
A good overview of how to formally document your architecture, and why you should care. But I found the terminology a little hard to follow, and I'm not sure I would be able to learn from this book if I didn't already have prior experience with this kind of documentation.
Although not specifically about documenting, I found 'Just Enough Software Architecture' was a more understandable justification for doing it.
Although not specifically about documenting, I found 'Just Enough Software Architecture' was a more understandable justification for doing it.
February 1, 2022
This review is for the 2nd edition (blue cover.) This book was so dense with helpful material that I used almost 10 sticky tabs to come back to sections more quickly. Appreciate the nod to TOGAF, RUP, DoDAF and ISO 42010 with supplemental descriptions and references. Speaking of references, they're amazing. Each end of chapter calls out to numerous sources, and there are plenty of "advice" and "for more information" sections that expand in summary or on suggested supplemental material.
February 25, 2020
Dans ce pavé, on trouvera des informations sur tous els types de vues utilisables dans la documentation d'architecture logicielle, mais aussi des éléments permettant de valider la complétude d'une documentation, avec des méthodes assez intelligentes.
Il y a par ailleurs un chapitre remarquable sur la documentation de décisions d'architecture, qui va bien plus loin que le simple "utilisez des ADR".
Pour le reste, la plupart des vues m'étaient déja bien connues, et ce livre se contentait d'en donner les forces, faiblesses et cas d'application avec un template de document qui, sans être inutile, me paraît assez lourd.
En bonus, deux annexes sur UML et SysML complètent l'ouvrage.
Ca en fait un bon point d'entrée à la documentation d'architecture, avec une méthode peut-être un peu dépassée par la révolution des conteneurs.
Il y a par ailleurs un chapitre remarquable sur la documentation de décisions d'architecture, qui va bien plus loin que le simple "utilisez des ADR".
Pour le reste, la plupart des vues m'étaient déja bien connues, et ce livre se contentait d'en donner les forces, faiblesses et cas d'application avec un template de document qui, sans être inutile, me paraît assez lourd.
En bonus, deux annexes sur UML et SysML complètent l'ouvrage.
Ca en fait un bon point d'entrée à la documentation d'architecture, avec une méthode peut-être un peu dépassée par la révolution des conteneurs.
June 27, 2023
I was between 3 and 4 stars, the book is not bad. It gives useful information and classify the information very nicely. I’ve heard or read before many of these information but the book made it structured in my mind. However, it explains everything in very detail and it made me bored so much. I would give up reading but then prefered skipping some sections.
July 26, 2017
Achei meio chato e com exemplos de diagrama que não são muito possíveis de aplicar. No entanto encontrei boas discussões sobre o que comunicar em arquiteturas, sobre tomadas de decisão etc.
June 9, 2021
Very good, a bit dry.
September 5, 2021
Way to pass "Examination of Software Architecture: Principles and Practices"
May 30, 2011
This is one of those books about which it is difficult to say enough good things. I found the first edition very influential on my on thinking to say nothing of enlightening. Impressively, the authors have improved this second edition, for example moving the comprehensive sample documentation online, thus making room for more of the lucid and rational explanation of documentation practices that made the first edition so useful.
I usually include a discussion of who would benefit from a reading in my reviews. Anybody who thinks they might be producers or consumers of software architecture documentation owes it to themselves to get a copy of this book now. Others might think they have no need for this book, but still should read it. This includes Business Analysts, who, this book makes clear, are stakeholders of software architectures. BAs will also their thinking sharpened on how to develop useful documentation and use graphical notation in a precise and meaningful fashion.
This book is on my short list of classics of software engineering. It is a book I return to often. Reading this second edition, even after being fully familiar with the first, was still a richly satisfying experience. I cannot recommend this book enough.
I usually include a discussion of who would benefit from a reading in my reviews. Anybody who thinks they might be producers or consumers of software architecture documentation owes it to themselves to get a copy of this book now. Others might think they have no need for this book, but still should read it. This includes Business Analysts, who, this book makes clear, are stakeholders of software architectures. BAs will also their thinking sharpened on how to develop useful documentation and use graphical notation in a precise and meaningful fashion.
This book is on my short list of classics of software engineering. It is a book I return to often. Reading this second edition, even after being fully familiar with the first, was still a richly satisfying experience. I cannot recommend this book enough.
January 7, 2008
Overall it's good substance but it's a little scattered through somewhat scholastic presentation and idiosyncratic terminology. I'd like to see (or perhaps write) a book that's half as long and that uses IEEE-1471 terminology.
Read
March 5, 2011Views is a powerful concept here because it accounts for the social complexities that one faces when they are asked to marshal an architecture role. If you don't understand these social dynamics, you will fail in a world of complicated stakeholders.
August 22, 2011
Documenting a software architecture is (very) difficult. This book aims to teach you how to document a software architecture, giving you clear advices (and a lot of knowledge) to accomplish your objective. Very well written, with a lot of examples.
May 12, 2012
Much, much better than the first edition. Unlike that version, this one has real world applicability.
Displaying 1 - 13 of 13 reviews