Document Your Reasoning Process

Good thinking is a learned skill. While some people seem to intuitively solve problems without much deliberation, the ability to consciously reason is something that has to be cultivated.

It’s possible (and pretty common) to stumble on the right answer without much careful thought, which can make the idea of documenting your thought process feel idealistic. But I think it’s crucial. Following a logical process allows for transparency, inspection, testability, and, ultimately, better learning.

I’ve walked into plenty of projects where bad decisions were undocumented, and I was left wondering what the hell the decision-makers were thinking—if they were thinking at all. Often, it’s the subordinates who end up suffering because they trust their leaders’ expertise without asking for a justification.

Here are two times this lack of reasoning documentation really got under my skin:

Anecdote 1: Making MongoDB Consistent

In 2015, I was contracted by a large biomedical company that was way behind schedule on a complex medical testing system. I was brought in to help align the front-end and back-end teams.

On day one, I was handed a 30-something page architecture document. Immediately, red flags. They were storing all of the system’s time-sensitive data in a MongoDB cluster, even though the robotics depended on a consistent state. This meant that patient A’s test could show as positive in one part of the system and unknown in another for quite some time.

When I pointed out the flaw, everyone agreed. They had already slapped on a MariaDB layer for consistent transactions and were talking about adding MongoDB transactions as a desperate last step. The original architect had been fired for being “too disagreeable,” and no one could explain why these choices had been made in the first place.

I didn’t want to mess with the architectural Jenga pieces without knowing why they were put there, and predictably, the project failed. My contract ended shortly after.

Anecdote 2: Paying for 15x Capacity

Another company I worked for had an ex-CTO who was so authoritarian that no one questioned his decisions, even when they clearly smelled wrong.

When I came on board, there was no technical documentation, so I reverse-engineered the system. I found all kinds of inefficiencies, including insane hosting costs. The company was paying for 15 times the capacity they actually needed. Since this was a production environment with legacy code and no instrumentation, I didn’t want to risk making big changes upfront. Instead, I started slowly moving parts of the system to a new hosting account.

Months later, after a $2,000 spike in hosting costs due to pricing changes, I pushed for a reassessment of the setup. When I asked the engineers about the existing capacity, they said the CTO had “guessed” and chosen the maximum available option. There had been past outages, but those weren’t even related to capacity.

I used a simple binary search method—halving the capacity every two weeks until I found the right balance between cost and risk. Ultimately, I reduced the capacity to 1/8 of the original, with only 12% peak usage (up from 3%).

This wasn’t advanced math. It was basic reasoning, but it worked. I documented this process in the company Wiki, so at least there was a record of why the change was made.

The Two Daemon Processes

These experiences have taught me to always document not just what I did, but why I did it. This habit has earned me appreciation from managers and, occasionally, “TMI” from teammates, but overall, it’s been valuable.

I’ve also realized that two distinct processes run in my mind when making decisions:

1. Fast Mind: An intuitive, top-down process that feels almost non-verbal.
2. Slow Mind: A verbal, bottom-up process that carefully analyzes details.

This roughly lines up with what Daniel Kahneman describes as “System 1” and “System 2” in Thinking, Fast and Slow.

Most of the time, my fast mind leads the way—and it’s usually right. But its inner workings are a black box, so I can’t always explain why it made a particular call. The slow mind, on the other hand, is great at crafting explanations, but those are often just post-hoc rationalizations for decisions the fast mind already made. This is known as confabulation: the mind’s ability to instantly BS a reason for what it just did.

This balance is usually enough for personal decisions, but it can be a problem in professional settings where you need to explain yourself to others. Before I trained my slow mind, I often found myself in situations where I knew something was going to fail but couldn’t articulate why.

Why Document Your Reasoning?

Start by asking Why? at every decision point.

• Why am I writing this post?
• Why am I using WordPress instead of a static site generator?

Your reasoning doesn’t have to be perfectly coherent or logically valid. It just needs to be intelligible to you (or anyone else who looks at it later). Even seemingly emotional or biased reasons like:

“Because I hate WordPress—some virus hacked my site once and now I just hate PHP.”

are better than going with a gut feeling or random choice. At least there’s some explanation to work from.

Bad Reasoning is Better Than No Reasoning

If you regularly question your reasoning, you develop intellectual honesty. Sometimes, “I don’t know” is a perfectly valid answer. Documenting poor reasoning is better than having no explanation at all. It gives others a starting point, reducing the chances of repeating the same mistakes.

Building the Habit

Start journaling your thought processes. Whether it’s a company Wiki, a public blog, or a private journal, just write down why you’re making the decisions you are.

If you hate writing, then seek out contrarian opinions in groups or forums. Discussing your reasoning with others can help you train your slow mind and sharpen your thinking. When I ran a meetup group, I’d share my technical problems with the attendees. Sometimes I’d learn that I had over-engineered a solution, other times the problems were difficult for everyone. Either way, the act of explaining my thought process made me a better communicator.

The Bigger Picture

This kind of reasoning isn’t just for tech. You can apply it to almost anything—health, relationships, politics, even mundane things like choosing deodorant.

Since 2016, I’ve written over 500,000 words in my private journal. Here’s what I’ve learned:

• My articulation has improved. I can now switch from fast to slow mind quicker.
• I’ve become more open to questioning my beliefs, which has made me more open-minded.
• I’m more forgiving of mistakes, recognizing how distorted our thinking can be—both mine and others’.

Documenting your reasoning isn’t just about clarity—it’s a tool for growth and self-awareness.