11 Communicating and documenting decisions

This chapter covers

  • Formalizing decisions using Pros-Cons-and-Fixes lists and Architectural Decision Records
  • Spreading knowledge through the company
  • Approaching your modeling process as a whirlpool of feedback loops

In chapter 9, we touched on the decision process and creating sustainability in that process. What comes after is communicating and documenting those decisions. In this chapter, we’ll talk about two documentation tools that will help you communicate decisions to your future team. We’ll also discuss how to spread the decision through the company so that everybody is informed in the right way. Lastly, we mentioned that you can’t make a decision and blindly follow the course of action that comes with it. The context in which you make decisions changes as you uncover information you didn’t have while making the decisions, which is why you need to keep your design decisions alive.

11.1 Formalizing a decision

If you’ve ever tried to understand a previous decision made by someone else, you know how hard it can be to understand what others were thinking when they made it. An important part of any decision is formalizing it, so that our future selves have access to the decision. There are two things you need to do to formalize a decision:

  • Find the consequences of the chosen alternative.
  • Capture the decision on paper.

Let’s start by looking at finding the consequences.

11.1.1 Finding the consequences

11.1.2 Capturing the decision

11.2 Spreading the knowledge through the company

11.2.1 Communicating decisions

11.3 Keeping the decision alive

11.3.1 The modeling process as a whirlpool