Documenting Software Architectures

Paul Clements

Mentioned 7

A complete, timely update to the classic work on capturing software architecture in writing • •Updated to use UML 2.0 throughout, with a complete Java/SOA-based case study, and covers architecture documentation in agile/lightweight/spiral environments. •Covers goals, strategies, rules, and hands-on best practices, and provides proven templates for generating coherent documentation. •Foreword by Grady Booch. This book's first edition offered breakthrough, start-to-finish guidance for software architects who want to document their architectures in a way that others can understand and accurately implement. Already a classic - and still a best-seller - this book has now been thoroughly updated to reflect today's most important software trends. Both an overview and a hands-on guide, this book introduces the uses of software architecture documentation; provides rules for sound documentation; shows how to document both interfaces and behavior; and offers proven templates for generating coherent documentation. This edition's extensive updates include: • •The use of UML 2.0 throughout. •A new case study based on Java and SOA. •Coverage of architectures generated via agile, lightweight, and spiral methods. •Updates for consistency with SEI's growing portfolio of architecture courses. •Clearer terminology and explanations throughout. •Coverage of frameworks such as TOGAF, DODAF, and FEAF. •Coverage of documentation tools such as wikis and Lattix DSMs. •New techniques for documenting variability across product lines. •Best practices for reviewing and validating documentation. •Comparisons of 'Views and Beyond' vs '4+1' approaches. •Improved alignment with the IEEE-471 standard. This book continues to stand alone in helping architects document their architectures so they will actually be implemented as intended.

More on Amazon.com

Mentioned in questions and answers.

I'm currently revising a number of document templates for my company. One thing we've never had is a formal Architecture Specification, so I'm starting to put one together.

What sort of things do you put into your architecture specs? Feel free to copy and paste a table of contents - that would be helpful. Are there any good templates already available on the web?

A good read: https://www.amazon.com/Documenting-Software-Architectures-Views-Beyond/dp/0321552687

You should write your architectural documentation with your stakeholders (e.g. developers, customer) in mind. The views and contents depend on what is necessary for the stakeholders. Therefore, the contents of your architecture can vary from project to project.

Can you please suggest some books on Software Architecture, which should talk about how to design software at module level and how those modules will interact. There are numerous books which talks about design patterns which are mostly low level details. I know low level details are also important, but I want list of good design architecture book.

Please also suggest some books which talks about case studies of software architecture.

I think this is the book that came to mind when I first read this question. It talks about various architectural styles like pipes-and-filters, blackboard systems, etc. It's an oldie, and I'll let you judge whether it's a 'goodie'.

Pattern Oriented Software Architecture

I also particularly like these two, especially the first. The second starts to dig into lower level design patterns, but it's still awesome in various spots:

Enterprise Integration Patterns

Patterns of Enterprise Application Architecture

I hope these are what you had in mind.

Where can you get knowledge about software architecture? One place is your experience building systems. Another is conversations with other developers or reading their code. Yet another place is books. I am the author of a book on software architecture (Just Enough Software Architecture) but let me instead point you to some classics:

  • Software Architecture in Practice (Bass, Clements, Kazman). This book from the Software Engineering Institute (SEI) describes how architects should think about problems. It describes the importance of quality attributes (performance, security, modifiability, etc.) and how to make tradeoffs between them, since you cannot maximize all of them.
  • Documenting Software Architectures (lots of SEI/CMU authors). The title of this book is a bit scary, because many people are trying to avoid writing shelfware documents. But the wonderful thing about the book is that it describes the standard architectural styles / patterns, notations for describing structure and behavior, and a conceptual model of understanding architectures. All these are valuable even if you only ever sketch on a whiteboard.
  • Software Systems Architecture (Rosanski and Woods). Goes into detail about how to think about a system from multiple perspectives (views). What I like particularly is that it gives checklists for ensuring that a particular concern (say security) has been handled.
  • Essential Software Architecture (Gorton). Small, straightforward book on IT architecture. Covers the different kinds of things you'll see (databases, event busses, app servers, etc.)

That's just a short list and just because I didn't list something doesn't mean it's a bad book. If you are looking something free to read immediately, I have three chapters of my book available for download on my website.

Can you please educate me on what are the software architecture design patterns that are available?

To elaborate my question, I want to read through different architecture design patterns and decide what suits my project requirements?

For example, there are Enterprise application design patterns, Enterprise Integration design patterns, ESB patterns, SOA patterns etc..

Thank you for your help.

Regards Sandeep

Patterns occur at many levels. Architecture patterns (i.e., architectural styles) are generally the largest in scope and cover the fundamental organization of the system. Design patterns are at the level of several collaborating objects. Bernd's suggestion of Fowler's and other enterprise patterns is a good one. Just recognize that those patterns tend to be more specific than these architectural patterns:

  • Layered (i.e., virtual machine pattern)
  • Big Ball of Mud
  • Pipe and Filter
  • Batch-Sequential
  • Model-Centered (Shared Data)
  • Publish-Subscribe
  • Client-Server (and N-Tier)
  • Peer-to-peer
  • MapReduce

Architecture patterns most often apply to the runtime structure of the system, but can also apply to its modules or its hardware allocation. One common mistake is to think that the Layered pattern applies to the runtime when it really applies to a system's modules (i.e., its compile-time dependencies). You can, of course, mirror your module structure in the runtime

These patterns are discussed in detail in my book, Just Enough Software Architecture, Fairbanks (2010). Most of them are also covered in other books including Garlan & Shaw (1996), Taylor, Medvidovic, & Dashovy (2009), and Documenting Software Architectures (SEI, 2010).

With the list of pattern names, you should be able to find plenty of web pages (I've marked this as a community Wiki so that we can add those links). The books are helpful too because they give you more insight on how to use the patterns.

For architectural patterns, read Pattern-Oriented Software Architecture Volume 1: A System of Patterns. patterns discussed are:

  • Layers
  • Pipes & Filters
  • Blackboard
  • Broker
  • Model-View-Controller (MVC)
  • Presentation-Abstraction-Control (Hierarchical MVC)
  • Microkernel
  • Reflection

I am looking for a Visio-like tool that would help me draw my information system at the component level.

The design will not fit on a single piece of paper and I would like a web tool with a sort of 'infinite' sheet of paper, and a proper navigation system.

An idea that crossed my mind for example is to use KML layers on Google Earth to draw the information system and navigate it. I don't know though how easy it would be to do a Visio-like drag and drop editor inside Google Earth.

Have you ever found such a tool? How do you handle bird's eye views of your information system?

Thanks for your help,

Jérôme Wagner

This question is very close to my heart. I spent years searching for a perfect way to visualize a system architecture. I can relate to a notion of 'infinite' sheet of paper as well.

I tried to utilize "Second Life" as an infinite surface on which to depict the system. As you fly over the area, you see the big picture - big structures representing the main modules and infrastructure connecting them. You can then descend and walk into the structure to see more low level design elements. Sounds crazy? Believe me, it was.

I was also writing my own visualization software where a system was represented by something remotely resembling water towers connected by multitude of pipes. I went too far but didn't get even close to satisfactory results.

As luck had it, I came across "Views and Beyond" approach some time ago http://www.amazon.com/Documenting-Software-Architectures-Views-Beyond/dp/0321552687/. This book fixed me. Instead of dreaming of some magical interactive solutions, I now have a solid and sound approach at my disposal. I simply cannot recommend this book highly enough.

I was just curious to know about how to become a good technical architect Or what are the things makes a Developer good architect. Please share your insights and articles.

Reading a book on C# syntax will not make you a good programmer, nor will reading a book on software architecture make you good at architecture. On the other hand, there were plenty of clever Roman engineers but any engineering student today can build things better than those Roman engineers. The difference is the knowledge that they can apply.

So where do you get knowledge about software architecture? One place is your experience building systems. Another is conversations with other developers or reading their code. Yet another place is books. I am the author of a book on software architecture (Just Enough Software Architecture) but let me instead point you to some classics:

  • Software Architecture in Practice. This book from the Software Engineering Institute (SEI) describes how architects should think about problems. It describes the importance of quality attributes (performance, security, modifiability, etc.) and how to make tradeoffs between them, since you cannot maximize all of them.
  • Documenting Software Architectures. The title of this book is a bit scary, because many people are trying to avoid writing shelfware documents. But the wonderful thing about the book is that it describes the standard architectural styles / patterns, notations for describing structure and behavior, and a conceptual model of understanding architectures. All these are valuable even if you only ever sketch on a whiteboard.
  • Software Systems Architecture. Goes into detail about how to think about a system from multiple perspectives (views). What I like particularly is that it gives checklists for ensuring that a particular concern (say security) has been handled.
  • Essential Software Architecture. Small, straightforward book on IT architecture. Covers the different kinds of things you’ll see (databases, event busses, app servers, etc.)

That’s just a short list and just because I didn’t list something doesn’t mean it’s a bad book. If you are looking something free to read immediately, I have three chapters of my book available for download on my website.

George Fairbanks

What is the key difference between object and component? Can anyone provide examples in Java that how objects and components are related? If possible, please provide some examples whether what are objects and what are components.

Assuming a general software architecture context...

All objects are components, but not all components are necessarily objects.

Components are the general name for elements used in views from the Component-and-Connector Viewtype. The Component-and-Connector Viewtype describes runtime (aka dynamic) views, therefore components are runtime structures (opposed to static structures) (Clements et al., Documenting Software Architectures: Views and Beyond).

A component is not something specific to a particular language, but rather a way of organizing and thinking about the runtime structures of a system so the people developing the system can understand how the system they are building promotes or inhibits specific properties. Therefore, the following are true statements:

  • an object is a component
  • some conceptual collection of objects is a component
  • even a collection of components is a component

How you partition the system into components is going to depend on what meaning you want to convey to your fellow developers and what properties you need your system to achieve. Components connect with one another at runtime -- e.g. one object instantiating another, a web client connecting to a web server, a subscriber registering on an event bus. If you're using an object oriented language like Java, all components will be made up of objects.

Other examples of components, these from Component-and-Connector architectural styles, include tiers (N-Tier style), filters (pipe-and-filter style), objects, and components. "Component" becomes a sort of catch-all in many architecture descriptions so it is better to be more specific when possible.

My team project for a CS software architecture class has submitted an "architecture chart" for our project. We are designing an online DAW (digital audio workstation).

I emailed the chart we made and sent it to the professor for suggestions but his only response was "This is not an architecture chart", so that wasn't really very helpful.

I'm pasting a link to the chart below so that everybody can view it. http://www.webkam.us/images/ArchChart.png

If anyone has any ideas about how to improve this or if anyone can provide a good example of what a correct architecture chart contain, please respond and let me know!

Thank you! Kameron

Some of the common best practices for documenting software architectures, off the top of my head...

  1. Diagrams should express a specific view (also called a perspective in some texts) and be clearly labeled as to what view the diagram shows. (e.g. is this dynamic, static, or physical? Alternatively.. component & connector, module, or allocation?)
  2. Only on view should be shown in a diagram. For example, a database cannot connect to a code package. One is a run time structure while the other is a static/code structure.
  3. Notations should be clearly defined, generally in a legend. Even if you are using a "standard" notation such as something from UML.
  4. Notations should be consistent, at least internally to the diagram if not the entire documentation set. This means that a box or a dotted line, for example, in one diagram represents the same element or relation as in other diagrams.
  5. Multiple views should be used to convey different granularities of abstraction. An architecture description will consist of multiple views, at a minimum one for each of the perspectives.
  6. The responsibilities for elements and relations should be clearly articulated, generally in an "element-responsibility catalog." I like to create a table that describes the responsibilities for the various elements and relations in a diagram in more detail. For example, "the database is responsible for persistent storage of user information."
  7. Descriptive prose, including rationale, should describe the key decisions that were made (and generally but not necessarily depicted in a diagram) and provide rationale explaining why the decisions were made including alternatives not considered. In the best case there will be a clear connection back to articulated architectural drivers. For example, "we chose to use caching library X to support performance quality attribute scenario XYZ..."

See "Documenting Software Architecture: Views and Beyond" for the "definitive" reference. If you want to use UML to document your architecture, see Part II of "Just Enough Software Architecture: A risk-Driven Approach" for a good treatment of the subject. There may be relevant chapters online of each book but they are worth owning.

To critique your specific diagram based on the above best practices....

  • No legend, what to boxes, lines, and circles mean? Is there a difference between a dotted line, arrow, and flat line?
  • What is the perspective? I see layers, clients, servers, and possibly code modules all referenced. You likely have mixed perspectives.
  • Mixed granularities of abstraction -- first, a "layer" can't use a "client" (one is static and the other dynamic though I'm guessing you intended to denote a sort of hierarchic relation?). Each level of the tree might be a different view, showing finer granularity of your abstraction.
  • No rationale or descriptive prose.
  • No understanding of elements or their responsibilities.

If you were going for a UML diagram I recommend clearly labeling what diagram you are using and still including a legend for the notation. Not everyone who will read your document has memorized all the UML diagramming notations.

On the positive side, it seems like you probably have a good understanding of the system, you just need some help figuring out how to write it all down using architecture best practices!