< Blog roll

The third hardest thing in programming

There are only two hard things in Computer Science: cache invalidation and naming things. — Phil Karlton

That quote has got to be one of the most popular quotes in the programming world.

Martin Fowler had it on his site as of 2009, but Phil Karlton is purported to have started saying it in the late 1900s while at Netscape. So the idea has been around for a long time and I would hope that we have all heard the quote by now.

But for what its worth, I have come to disagree about those two things being the ONLY hard problems in computer science, and as such I’d like to offer up my thoughts on what would be #3 on the list of hard things in computer science.

Writing things down is a lot harder than it seems at first#

I think #3 on the list should be something along the lines of “writing things down to use them later”, or “documenting decisions and rationale for posterity”. Working on the design system teams where I have, a large chunk of the work is making decisions about how components should look and behave on behalf of an entire organization and then trying our best to document how and why all those decisions were made.

The concept is deceptively simple. Every time a decision is made about something, write it down and store it so you can remember and refer to it later on if/when the topic comes back up.

But I’ve never seen it actually work in real life.

I’ll try to lay out some of the reasons I think writing things down is so hard, some of the things I’ve tried, and a little bit about our good friend AI probably won’t really help.

First, about the pressure to go fast#

I have always worked at large companies. Anyone that has worked at large companies can tell you that trying to do anything will feel very slow at first. There are always what feels like too many meetings, too many stakeholders, and too many disruptions to actually shipping. Yet somehow we still feel like we manage to ship lots of work over a given period of time. We are always amazed at how much we‘ve gotten done, even if a startup company would have gotten a lot more done in the same amount of time we think. We start to measure our successes over months, program increments and quarters instead of hours, days, and weeks.

So I already know that I probably work slowly. I have also work on enterprise teams building shared tools like design systems that need to consider approaches from lots of angles before delivering. We tend to overanalyze and overthink features a ton because of the amount of teams and people those features potentially affect. So being on an enterprise team in a large company is a double dose of working slowly.

But that doesn’t mean there isn’t intense pressure to move faster and faster ever day. No matter what we ship or value we produce, we should have done it faster. We should have found a way to do the same amount of consideration and quality in a shorter amount of time somehow while maintaining the all-important work/life balance.

Every roadmap planning session has us debating how many things we can get done, and probably stuffing too many things into the todo list. Even writing down the roadmap and doing PI planning feels too long and too slow. We’d rather be writing code or producing designs than planning out and prioritizing the work ahead of us.

AI has made this pressure to go fast much, much worse. Leaders everywhere have drunk deep of the AI hype koolaid and are chomping at the bit for 200% productivity increase. If only we could burn enough tokens we could ship the whole company’s OKRs in 5 minutes and not have any bugs or performance degradation. The doers on the ground have always felt this pressure, but the “now you can go even faster because we gave you Claude” pressure that comes with AI piles on tenfold. Stop looking at your code output, vibecoding only. Only pause your work if you can build a humanless agentic pipeline so you can burn even MORE tokens so that the bots can do even more work than you while you’re also doing more work.

I think the pressure to move fast has multiple impacts on writing down decisions.

Writing things down is process, and adding process means going slower#

In a team setting, you can‘t likely just start writing things down willy-nilly and expect it to work. There have to be guardrails and common understanding and buyin for such a thing to take hold. That means adding process to your team‘s workflow. Every doer in corporate world has been conditioned to think that more process means going slower. They are usually right.

The small bits of friction that we experience when we try to start documenting everything chip away at our enthusiasm immediately. Things like

all feel like we‘re adding a “heavy process” that will slow us down in the future. And when we establish this process, we do so with a vague perception that it might help us down the road. We are all pretty convinced that there will come a day where searching the decision log will help us not have to revisit a topic we‘ve already discussed and rehash the same ideas. We are right about that also. No one much likes more process, but if you want to have decisions documented at some point in the future then you have to add some and cultivate the team culture that writing things down is important.

There is a lot to log to make decision-logging truly useful#

Part of why it might be a heavy process is that to truly make decision-logging useful, there is quite a bit of metadata you probably should capture along the way. It strikes me that it is not necessarily enough to just write down the decision was made and what the rationale was for that decision. The ADR (Architectural Decision Record) process and document templates out there have a ton of information about decisions like:

Looking at all that metadata, its easy to see that the ADR structure is way too heavy for all the small decisions that we make on a daily basis. But the small decisions along the way still might have some important metadata to capture, like the people involved or the date it was decided. It might be nice to come back to a decision log and note that a decision was made, but the product owner and tech lead were NOT in the discussion, etc.

So a lot of teams (including every one I‘ve ever been on) don‘t invest in documenting decisions because of how heavy the process feels vs how fast they feel they need to work and produce.

The most important time to write something down is when you don’t need to have it written down#

Another reason that writing things down is so hard is literally that the best time to store the outcome of a decision and the rationale used for that outcome is right after the decision is made. But at that point, it feels redundant because the conversations, discussions, and agreements are all fresh in our minds. We literally just got out of the meeting where we came to a consensus, so it feels redundant to send update the decision log and send out the communication to the team informing them of the brand new decision that everyone already knows was just made.

Speaking back to the above point about recording decisions feel like a heavy process, I have been in meetings where decisions where recorded during the meeting (as they probably should be) and the simle act of recording the decision has derailed the productivity of the meeting because everyone went from participating in discussions to watching someone type into the log on the screenshare. Could they have just taken the logging of that great decision as an action item for later such as to not derail the meeting? Of course! But actions items are where good intentions go to die. Saving something boring and procedural like writing something down as a “action item” for later is a practical guarantee that it won‘t get done, or some detail or rationale will get lost. After a big meeting with lots of stakeholders, everyone wants to let down with a cup of coffee, or check emails and slack messages, or worse still go to the next meeting of the day. Its best to log a decision immediately, but that little bit of process can feel supremely heavy and slow.

So people and teams start saving the logging step for later and then eventually stop doing it altogether.

Its hard to know when/where decisions will get made to prepare for them#

Another consequence of the pressure to move fast is in how that pressure changes how we work. We all have too many meetings already, so the last thing we need is another structured, agenda-ed calendar invite to attend where we can all make decisions together as a team and share context. Sure we still do that for the big decisions that need making, but what happens to all the little ones?

Because big team meetings feel slow, we opt for pullups and pairing sessions one-on-one or in smaller groups. I‘d argue that these small sessions end up being where most of the decisions get made. They probably tend to be smaller in impact, like the difference between “this property should be a boolean because…” and “the overlying architecture for the whole product will be…”, but the size difference means that there a billion more small decisions than large ones. And all the small decisions are the ones that end up getting lost and rehashed the most. You will probably find yourself rehashing the API of a component more often than the tech stack of your product. But because that decision was a small one, the rationale for why that property was made the way it was is probably lost.

We don‘t trust automated solutions#

Because its hard to know where decisions will get made, particularly as we work in smaller groups to try to go fast, it is always tempting to reach for an automated solution. There are lots of products out there that can record and transcribe meetings for us. It seems fairly straight-forward to set up a tool that just transcribes every meeting and delivers the text to someone for processing to record decisions. Admittedly, this might be an area where the chat bots would help out. They might be decent at taking a meeting transcription and turning it into a log of the decisions that were made during that meeting. They might even be able to update the decision log directly depending on how all of that is wired up.

But I think you would find that humans start acting differently when they know they are being recorded and every word they say is being tracked. You might find that a lot of people get uncomfortable in that situation. They might be the same people that balk at cameras-on for meetings policies and such. Personally, I don‘t mind but I recognize that I am probably the outlier. But in any case, I would still argue that in order to get good decisions made, the environment needs to be a safe space for dissent and healthy disagreement. Maybe that‘s because I am always the one pushing back, I dunno. But what would happen if team members start holding back their opinions because they are on the record and would prefer to state their truth in another off-the-record type way? What if there is no off-the-record avenue for those people? You might start getting less healthy pushback in the decision meetings and end up with a worse outcome merely because of the recording setup.

That is a bit of speculation on my part, but I have definitely worked with people that did not like being recorded, so I think its a plausible argument to make as to why automated solutions might not be a panacea. In any case, I would bet that some human would still need to remember to hit the record button most of the time which would still end up losing decisions as humans forget to do so.

Storing decisions is tedious and clunky no matter where#

But with AI, now everyone is writing spec files, right? Surely spec files will help?

I don‘t think spec files really help all that much, even though the onslaught of AI hype might have us think that spec-driven development is the way of the future. Don‘t get me wrong, I think we should create specs for certain things, but even when we do, we rarely add the details that we will end up wishing we had later on, and I don‘t think having AI consume specs changes that. I think that storing decisions is clunky almost no matter where the decisions are.

Here are the mechanisms I‘ve tried for storing decisions and their relative purpose:

There are probably a lot of different places to store a file, so I doubt that the problem lies with Google Docs or Git/Github as a storage mechanism. But as far as I know, we are pretty limited to decision storage mechanisms. I think all we have to choose from are files or threads. I‘ve never worked on a team that had a database of decisions or anything like that.

Assuming I‘m right that files and threads are the only ways we can document, both of them leave a lot to be desired. Either at decision entry time, or when its time to get our decisions back out again so we don‘t have to rehash a conversation.

There isn‘t a good way to search decisions even if you do manage to log them all#

For the sake of this topic, let’s assume that you do manage to get a team culture and process such that every decision you make is logged with its rationale in some form. That would be amazing and props to you for your cultivation of team culture. How would you get those decisions back out again? If you chose files as the way to document those decisions, then searching them all is going to be a pain, especially if there are multiple places the files could be like it has been on my teams. As far as I know there’s no tool that can search across markdown in Github, and spec/log files in Google drive simultaneously.

And don‘t even get me started on Github or Slack search.

Gif of Captain Jack Sparrow making a disgusted face

I have only explored a little bit of how AI could possibly help here. Maybe searching a ton of files on Google Drive is something Gemini is finally good at. That would be cool. If there was a way to wire up a decision log to an AI bot, it might be able to pull out relevant decisions and metadata to act as a search. That also might take development work to set up, or more tedious manual copypasting of decision records into context. Either way, AI can only help us search through our decisions if we first find a good way to store them. In the section above, I have my doubts, so try as it might, AI might not be able to come to our rescue here either.

We can‘t measure the impact of our good decision to write things down#

And at long last after spending all the time and tedium of writing so many things down, do we have a way to measure that our effort is actually paying off? I don’t think we do. Since logging decisions is so much effort in the first place, it would be nice to know that we had saved hours of time not rehashing settled decisions. It would be nice to know that we saved an external stakeholder some time by being able to prove that we did our due diligence when we set things up the way we did last year. But tracking the time saved not rehashing old decision is probably the same amount of effort of writing the decisions down in the first place. There will be no dashboard of time saved not having to have pullups about the same topic 3 times.

The best we can do is to have a collective team vibe about how well-organized we are because the decision search turned up some good results a few times when we needed it. I doubt that the future vibes are very much worth the present effort. I think part of us knows this in the very beginning which circles up back to the very first topic about decision logging feeling like heavy process. Process feels heavy when we’re not really sure what we’re getting out of it (looking at you story pointing).

I think I would get a lot out of a good decision logging process and mechanism. But I can‘t prove it. And I’ve never worked on a team that ever got to a point where all the decisions were logged effectively. I doubt you have either, but if you have, I’d love to know how you do it!

You after reading this:

Gif of Ryan from The Office taking notes

The End