#44 - Learning from the Past with Decision Logs
How Git Commit Practices Can Help Track and Improve Decisions Over Time
Intro
I once worked in a large organization that frequently restructured its teams, roles, and hierarchies to adapt to changing goals and realities—sometimes as often as once a year. Over time, it started to feel like history was repeating itself, as the lack of knowledge about past decisions frequently led to poor outcomes.
At one point, the organization had structured itself around geographical management—each site or group was overseen by someone managing multiple disciplines and roles. Later, after reflecting on various insights, management shifted to a profession-based model, where roles were managed independently to allow disciplines to grow and specialize (similar to guilds in a squads model).
Years later, they reverted to the original geographical structure for various reasons. What concerned me wasn’t the decision itself but the fact that no one seemed to remember why it hadn’t worked well the first time. Unsurprisingly, the same issues reappeared.
I believe we can learn a lot from how codebases are managed to avoid these organizational problems.
Enter Git Commit
A commit in Git represents a piece of code added to the codebase. In the diagram above, the main branch reflects the current state of the code. To reach this state, you must pass through all the changes made along the way—from A to F. This concept is similar to event sourcing.
When committing to the code, you must include your identity and explain the change. This combination allows for valuable insights, such as:
Who last modified this line of code? (via the “blame” feature)
Why did we add this function?
When was this file deleted?
Additionally, Git allows you to return to a previous state of the code at any time, like reverting from point F back to point E.
Why do we need it?
Putting the technical jargon aside, consider you have a recipe for a cake. Over time, you start experimenting and improving the recipe. Maybe even other members join and update based on their own taste. Eventually, you have only the final version with zero knowledge of how it got there or that something even changed.
As computers became common and you could develop software on personal computers, the need for collaborative work increased, and source code management (SCM) was created. With it, we can work on scale, collaborate effectively, and recover quickly from incidents.
Back to the re-organization
Returning to my initial story, let’s imagine this was the case:
The ability to scale and learn from past experiments improves when historical changes and who made them are visible. Additionally, working with context is always the better option.
In reality, managing decisions for a team or a company isn’t like managing code. However, it can be done using decision logs.
Tips for effective decision logging
You can get started with your own Decision Version Control system today:
1. Create a Simple Google Sheet: Set up a Google Sheet with columns for Area, Date, Decision, and Owner to track all significant decisions.
2. Set a Review Timeline: For each decision, determine a time to revisit it (e.g., six months from now).
3. Automate Reminders: Set automated reminders for essential decisions to prompt a review at the appropriate time.
4. Conduct Retrospectives: When reviewing a past decision, ask yourself if it was right and what lessons can be drawn from it.
5. Leverage Historical Context: Review past entries in the same area before making new decisions to gain valuable context and avoid repeating mistakes.