Decision Log

Fork this template on Google Docs

Something about the close-knit social chemistry of a small team gives them a shared brain. Of course you know that last week Michelle decided all new frontend work would happen in Typescript. Ambient awareness is less and less effective as an alignment tool as an organization grows, and becomes quite unreliable as an organization grows past ~twenty folks.

One tool that folks use to scale alignment around key decisions is the “decision log.”

Screenshot of hiring ratio template.

Decision logs collect open and finalized decisions in a single, versioned document where anyone in the organization can quickly check if a decision has been made on an important area. They’re also a phenomenal place to collect links to the documents and forums where the decisions were made; when a decision is revisited in the future, the rationale behind how a decision was made is often much more important the decision itself.

How to Use

  1. Fork this template in Google Docs
  2. Think about important decisions that have been made over the past year and use them to preseed the closed decisions
  3. Ask around the organization about the most important decisions that currently aren’t made. The sorts of implicit unasnwered decisions that are making decisions in your architecture review meetings difficult to align around
  4. Agree with the team or leadership within an organization that folks will commit to tracking decisions in the decision log during a trial period of three months
  5. Share with the team, and make the decision log easy to discover by linking it from related documents (RFC templates, Architecture Slack channels, etc)
  6. Review adoption after three months and decide whether it’s a good practice for your organization to adopt or if it’s better to unwind and explore another solution

Tips

  • Decision logs are only helpful if folks know they exist and use them. Tie them into your processes: link to your #infra room in Slack, inform new hires about them in their onboarding document, link to them from the top of your RFC documents and include important RFC decisions in your log as well
  • Start out with fewer, more general decision logs (e.g. one for all of Infrastructure) rather than numerous, specialized decision logs (e.g. one for Compute, one for Data Platform, …). This makes it less likely that they silently go dead
  • If you stop maintaining the decision log in a specific area, that’s ok! Just make sure to explicitly mark is deprecated rather than leaving a stale resource