The Well-Considered Decision

It’s all about the journey

I failed my first Math test in school. I failed it, even though most of my answers were correct. “How much is 1820 divided by 5?” “364” I answered. 1 point out of a possible 5.

Why?

I didn’t show my work.

In Math, as in many disciplines, most visibly in school, it’s about the journey, not the end result. How did you get to your answer? What were you thinking? What were the approaches you considered? Why did you pick this answer, and not the other one. That’s how you will be graded.

Once people leave school, they assume that the need for “journaling the journey” is over, and it’s only end-results that matter.

Perhaps sadly, that’s not the case.

“Show your work” is the essential part of communicating to others and your future self that your decisions are well-considered. While at this stage of your career there won’t be a teacher that requires this look-inside-the-mind to be able to grade you, there is a lot of value in taking this approach anyway.

For example:

1. It is documentation for the future. Documentation of software is a tough problem. We have mechanisms to document classes, and methods. We create architecture documents. However, design decisions are often poorly documented. As a result, in a year, five years, ten years somebody will look at a piece of code and will be like “what bozo came up with this crap?” There may have been good reasons, but they are nowhere to be found.
2. It results in better decision making. For two reasons:
   1. writing it down, and following a certain format (that I will describe later) forces you to more consciously do your due diligence, be sure you’re making the right call; and2. writing it down, ideally before making the decision, makes it easy to get input from others, and get access to other points of view.
3. It creates trust. This is valuable especially if you do not yet have a (good) reputation in your team or organization. If you show people how you think and how well you consider your decisions, they will more easily trust your future decisions. If you jump to conclusions directly, they will often not trust you’re making the right call without some deep digging and challenging, or even dismiss your decisions outright.

Ironically, it is my experience that the more senior the engineer is, the more likely they are to solicit input on their “journey.” How? By showing their work and asking for input.

So, how do you document your decisions?

Here the four main parts I look for:

1. What is the problem? Decisions for the purpose of making a decision are pointless, there needs to be a problem to be solved that warrants a decision. You may assume the problem is obvious to everybody, but often time it is not — state it clearly.
2. What solutions exist? A problem rarely only has one possible solution, in fact there is at least always one alternative to consider: do nothing. Describe all reasonable solutions.
3. What are the trade-offs? No solution is perfect, there’s always costs and benefits. Trade offs can exist at various levels: purely technical, architectural, deployment/operational, scalability, and even product-level trade-offs have to be taken into account.
4. What do you recommend we do? Now that all plusses and minuses are known, what do you recommend we do? Or even: what have you decided to do?

Dun dun done.

Sounds easy? It’s not. But it’s worth the journey.