Documenting Software Architecture

This page is part of the guide The Practical Software Architecture:

  1. Software Architecture Issues and Solutions
  2. The Process Overview
  3. Documenting Software Architecture
  4. Vision, Principles, and Constraints
  5. Preparing the Roadmap
  6. Decision Making
  7. Conclusions

As we saw in the previous section, it’s essential that we take some notes during meetings and design sessions and we keep them for future use: the need of a redesign, sharing with others, etc.

The Architecture Guide is an alive, evolving set of documents. It’s the tangible outcome of the Process (even being digital – you can read it). It holds the designs, conventions, and decisions you made as part of the process.

Both the Guide and the Process are important so you shouldn’t focus only on one of them. If you get a perfect Architecture Guide without a good process supporting it, that will be like giving a book to the development team and hoping that they’ll follow it without questions; that’s a top-bottom approach unlikely to succeed. On the other hand, if you have a very efficient process but the results are not properly organized and documented, you’ll experience the déjà vu effect.

The owner and ultimate responsible person for keeping it up-to-date should be the Software Architect(s), but the contributors might be many. Think of the Architect as an editor reviewing and organizing pages created by developers, giving consistency and providing a high level of organization. I know that we as developers (I consider architects as developers too) don’t like to write documentation so it’s hard to get others to contribute; anyhow, you should encourage it.

For the elaboration of this Guide, I strongly recommend you to read the book Software Architecture for Developers (Volume II), written by Simon Brown. In that practical book, you’ll see a detailed description of all the sections that you should include in your Guide and good advice on how to keep it focused on what’s important. It also covers the C4 model, a very useful way to visualize Software Architecture. These are the headings proposed in the book:

  1. Context
  2. Functional Overview
  3. Quality Attributes
  4. Constraints
  5. Principles
  6. Software Architecture
  7. Code
  8. Data
  9. Infrastructure Architecture
  10. Deployment
  11. Operation and Support
  12. Development Environment
  13. Decision Log

My recommendation is that you use any kind of document sharing tool already available in your company and set up a dedicated space with these sections as placeholders. Make sure that all project members can see and edit. It should provide changes history so you know what changed in a page, when and who modified it. Link there any existing documentation that you already have and that you consider useful (only if you can keep it lightweight and to the point, try to avoid building a Frankenstein Guide copy-pasting from multiple docs with different styles). As an alternative, you can also create an extra section, Legacy Docs, and index there your old documents. Then you can incrementally build your new Guide using the Process described below.

Continue now to Vision, Principles, and Constraints in Software Architecture