Use a decision log to record context

Program management’s primary (tangible) output is documents. One document that doesn’t get used very often is the decision log. It’s just what it sounds like: a log of decisions.

Why have a decision log?

The main reason to have a decision log is to leave notes for the future. Later on, future you or your successor or others in the community will wonder why you made a particular decision. Years from now, the decisions you make might seem ridiculously bad. So you leave a record of the context.

It can also save time when someone suggests an idea that’s been considered before. It’s not reasonable for you to expect people to know the entire history of your project before they joined. So naturally, people will offer suggestions that were considered and rejected in the past. That doesn’t mean the reasons for the rejection still hold; it means you have a record of what was considered. This gives you a shortcut: you can look at the reasons a decision was rejected and decide if they’re still valid before putting a lot of effort into it.

Full disclosure: I have not kept a decision log in my role as Fedora Program Manager. Perhaps it’s time to start.

What to record

A lot of sites talk about including a unique ID number in a decision log. I question the value of that in corporate contexts (will people really say “decision 541” or will they say “the decision to use Python”?), but it’s almost certainly overkill for open source communities. You can include categories, though. For example, if you want to group your decisions for the database, the project’s git server, and security policies separately. Categories make it easier to find the decision you’re looking for.

But in general, you want to record what was decided, who decided it, when it was decided, the major factors, and any alternate choices. I like the approach of starting with a question. For example: “what should we use to build the website?” For that decision, you’d record the following:

• Category: website
• Question: What should we use to build the website?
• Decision: We will use WordPress to build the website
• Decided by: Ben Cotton, in his role as Chief Duck Alignment Officer of Duck Alignment Academy
• Date: 2021-12-27
• Factors:
  • Ben’s already familiar with WordPress
  • WordPress is a sustainable project
  • It has a mobile app
• Alternate choices:
  • Artisanally hand-crafted HTML: too much work
  • Hugo: I’d have to learn something else

You can go into more detail if you’d like, but that’s at least enough to look back on later and have a general understanding.

How to store your decision log

Because your decision log is a record for later, you want it to have two particular characteristics: available and searchable. If it’s stashed away on someone’s thumb drive, it does the project no good. And if you have to search through each record one-by-one, you’re not going to do that. Bonus points if it’s also filterable.

I’m not aware of any open source software specifically designed for decision logs, but you could write your own with a relatively simple database. But an easier approach might be a shared spreadsheet. A wiki or documentation page will work as well. You could also store it in a git repository. Each decision could be a separate file (perhaps in a particular directory for sorting purposes), but you’d want to have an index page to help with searchability. You could also use a git forge’s ticket system or a blog — these would allow you to easily apply multiple labels, which could help with search later.

The point is that whatever your community will use is the right choice. A decision log is useless if no one uses it. Maybe “what should we use for a decision log?” will be the first entry you make.

Photo by Javier Allegue Barros on Unsplash