Sam Gentle.com

Decision log

I've had an interesting problem come up a few times on long-running projects. Throughout the project you make a lot of different decisions. You choose one particular solution over others, make some tradeoffs in how you design something, and set or change overall direction. These decisions accrete over time until, late in the life of the project, there's a thick, hidden blanket of existing decisions underneath everything. For solo projects you can often remember why something was done, but not always, and for teams it's basically out of the question. The result is you often waste time revisiting decisions.

Existing forms of documentation aren't so great for preventing this. In software you would usually attach documentation to a particular line of code, a general design document, or a larger code review/patch set. Those can explain particular instances of decisions, but I don't think they solve the problem completely. You end up with that information spread out over a lot of different places, and in a lot of cases a given decision spans several different locations. I think that decisions don't map cleanly enough to anchor points in the project itself for that to work.

Instead, I think it might be worth keeping a decision log. Just a flat file of all the decisions you make about a project, maybe split into multiple decision files if you've got neatly separated subprojects. Every time you decide something important, it goes in. The bar for important might need some tweaking, but I think a good one would be anything that takes longer than a minute to decide on. Alternatively, anything you could imagine wanting to know if you hadn't seen the project before.

The end result would be a single place to look if you're trying to figure out (or remember) why something was done a certain way. I think it'd also have the nice side benefit of encouraging you to think about your decisions in the context of that some future person trying to understand what you were doing.