Explain the Rationale for Your Decisions
Design rationale describes why we made each design decision. Maybe you chose a pattern to promote a certain quality attribute. Maybe you picked a technology the team is familiar with or one that had the right cost. Every decision had alternatives, pros, and cons. We weighed trade-offs among properties and justified our conclusions through some logical thought process.
The better downstream designers understand the rationale for your decisions, the better they can embrace the intent of your design. The better others understand the intent behind your decisions, the more likely they will be to uphold the architectural integrity of the system as it evolves.
Rationale in an architecture description comes in many forms. It might be prose, a story, or a couple of bullet points. Sometimes your pile of rejected decisions can be more telling than a lengthy explanation.
Describe the Paths Not Taken
Developing software is a journey. The path is winding and there are dozens of roads leading to the same destination. Every fork in the road, every decision you make, is an opportunity to help others understand why the software architecture is the way that it is. One method for helping people understand the decisions you made is to enumerate all the options you rejected.
Consider the paths not taken in the Project Lionheart architecture. See the table.
Path not taken | Discussion |
|---|---|
One huge web application | Doesn’t allow us to schedule computationally intensive operations |
Java for Display Business service | Several teammates know Node.js, promote maintainability with JavaScript in the client and server |
Index RFPs in SQL database, search service reads the database directly | Doesn’t give an expressive enough query syntax required by stakeholders |
MongoDB for data storage | While it seems like a good fit, no expertise on the team |
Isolate services to their own containers | Not enough familiarity with technology. We can ship sooner putting everything on the same VM. This decision is not binding. We can change strategies later. |
Not everyone can be in the room when we make a decision. Reading the paths not taken lets you play back decisions so others can get a feeling for the architecture’s journey. Without this knowledge, it’s like watching the last five minutes of a movie. You missed all the character development and anything the characters do at the end will seem random. When you have the background, Darth Vader’s decisions at the end of the Return of the Jedi hold a deeper meaning. Without the background, you might think Vader is just fickle and annoyed.
You will always reject many more ideas than you keep. Humans can dismiss dozens of options in the blink of an eye without even realizing it. Formally record any decision you discuss as a team. If you notice you’re having an intense inner monologue, try to externalize your thoughts so others can benefit.
Get Your Hands Dirty: Describe the Paths Not Taken for a Project
Think about a recent project. Write down some of the alternative architecture choices that your team considered and why you rejected each option. Of these decisions, who on your team can describe the rationale for the decision?
Here are some things to think about:
- Were there any major discussions you had as a team?
- What decisions did your team struggle to make?
- What decisions were made under uncertainty?
- Were there any point of no return decisions that forced you down a particular path?