Tell the Whole Story

In ​Build Models into the Code​ you learned that there will always be a gap between the models in the architecture and the code we write. We can close the model-code gap somewhat, but we can’t express every architectural design decisions in code. Nevermind that few stakeholders can read code and no code exists at the beginning of a system’s life when design planning is most needed.

We need architecture descriptions for several important reasons.

Get organized.

Building software is as much about working with people as it is working with technology. Architecture descriptions show how everything comes together. Whether we are assigning responsibilities to teams or letting people self-organize, everyone needs to know how components in the system work together so they can align themselves accordingly.

Establish the lingua franca between technical and business stakeholders.

Every stakeholder has a right to understand the architecture. While models establish the vocabulary of design, the architecture description translates those models into ideas different stakeholders can understand. One of the most important jobs of an architecture description is to show how the business goals and quality attributes are addressed in the architectural design decisions.

Put a spotlight on quality attributes.

Quality attributes are often out of sight and out of mind. The architecture is the one place we treat quality attributes as first-class citizens. Keep quality attributes at the front of everyone’s mind by making the architecture a real thing that people can see, read about, and talk about.

Clarify thinking.

It’s easy to believe you have everything figured out if nothing is written down. When you put pen to paper, you’ll realize how mushy the ideas in your head really are. Writing an architecture description forces us to confront our knowledge and come to terms with what we know, what we think we know, and what we don’t know.

Create something you can evaluate.

We can’t reason about things we can’t see, touch, or share. We also can’t afford to wait for every design decision to be realized in code before critically evaluating it. Architecture descriptions give us a way to analyze our design decisions while it’s easy to make changes. Spending the afternoon explaining a dumb idea to someone is much better than spending a month implementing it.

Show it off.

Software architecture is cool! You poured your heart and soul into designing a beautiful software system. The whole world should appreciate it! Architecture descriptions are the best way to brag about the software systems you’ve built. A good architecture description projects confidence for customers and upper management. It shows leadership by clearly articulating a purpose, plan, and vision.

Architecture descriptions are supremely valuable. The trick to getting the most bang for the buck is to choose the appropriate description methods for your current project and team context.