Documenting decisions

[Alan Karp]

At friam today I mentioned a form for documenting decisions that I learned while working with Intel on the Itanium project.  I've found it to be so useful that I write up decisions just for my own use.  Baldur asked me to send an example to this list.

The sections are:

• What the decision is about
• Stakeholders who might be interested
• The decision you made
• Objections to that decision
• Alternatives you considered with reasons they weren't chosen
• Reasons for the decision

https://github.com/alanhkarp/SitePassword/blob/PBKDF2/DesignDecisions.pdf is an example.  I left out the Stakeholders section, since it's just me.  That field is really important in a team larger than one, because stakeholders often know why a given decision is the wrong one.

Doing all that writing seems like a waste of time while you're doing it, but I've found it has advantages.  Just writing things down helps me clarify my thinking, particularly in thinking up new alternatives, some of which I've ended up adopting.  The second is saving time down the road when you've forgotten why you chose the way you did.  In a bigger organization, these write-ups are a valuable resource for new project members.

--------------
Alan Karp