Chapter 11
Describe the Architecture

Software architecture documentation has a reputation for being notoriously awful. It takes time away from writing code. It always seems to be out of date. It’s usually written in some proprietary binary file format that you can’t edit. And on top of all that, nobody reads it anyway! It’s no wonder some people call software architecture descriptions SAD!

Bad architecture descriptions make us sad. Great architecture descriptions give our team clarity of vision. Great architecture descriptions are a planning asset, a communication aide, and a collaboration tool. They improve the quality of the software we build by helping our design decisions reach everyone.

In this chapter, you’ll learn how to create amazing software architecture descriptions that people love. Why will people love them? Because you’ll give your audience the exact information they need in a humane and easy-to-learn format. Love is a strong word to apply to software architecture descriptions. I mean it. Creating an amazing software architecture description is easier than you may realize.