Documenting Software Architecture

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.

• Architecture Guide Templates
• Tooling

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 don’t like to write documentation so it’s hard to get others to contribute; anyhow, you should encourage it.

Architecture Guide Templates

For the elaboration of this Guide, you can use one of the templates available online:

1. There is a template described in the book Software Architecture for Developers (Volume II), written by Simon Brown. In that practical book. It also covers the C4 model, a very useful way to visualize Software Architecture.
2. You can find another example in this template, created by Gernot Starke and Peter Hruschka. It has a Creative Commons license and is fully available online for your reference.
3. As you could expect, I also created my own template and shared it via Github. This template focuses not only on the core Architecture Guide itself, but also in sections to hold the process artifacts: designs, decisions, roadmap, etc.

These are the six main sections of The Practical Developer’s Architecture Guide:

1. Guide. An evolving set of documents explaining your Software Architecture and related topics like common patterns and operations.
2. Roadmap. The 'Make it happen' section. Includes the planning over time.
3. Designs. Each team should populate this section with new feature designs.
4. Decisions. Keep your Architecture Decision Records here. Includes the template and an example.
5. Journal. Holds meeting notes, whiteboard pictures, etc.
6. Modules or Teams. Contains documents and designs that have a local impact.

Tooling

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