I have been on many development teams and as the team matures decisions about direction are made. These decisions often come back up over and over. Like why don't we fill in this field why didn't we use memcache over a custom solutions. These decisions add up over time and become a significant part of style guides coding standards and unit tests.

My question is I have never run into a good way of tracking these decisions or the discovery that went into making them. Does anyone have a best practice.

4 Answers 4


(in my experience)

Major decisions (especially involving product owners) belong in design documents.

Trivial technical decisions (why is is field empty?) belongs in a comment right next to the field.

In between sort of decisions are odd. I tend to think that undocumented communal knowledge is best, since documentation of a decision is useless if nobody follows it and these medium decisions are often things that everyone needs to follow. I've seen wikis used for this with little success. Especially for style guide stuff, having it in code is often "good enough" for people to go with the flow.


Agile Software Development Methodology does address these development decisions very efficiently. At the end of each iteration, we can have retrospective session. We jot down our lessons that we have learnt over a period of time and review them before we initate the next iteration for improvement.

I would suggest that you shold look into Using Large Agile Retrospectives to Improve Projects

  • 3
    So I have used retrospectives. Don't you find after a year or two it becomes difficult to categorize when and where a decision occurred
    – rerun
    Oct 23, 2013 at 17:07
  • It all bolis down to how you organize and review your past retrospective sessions. While reviewing, a project manager should ask what was the prbable cause of making a decision and carrying out a certain line of action in a certain iteration. For this reason people often use an agile project management software to track and organize project histories.
    – Maxood
    Oct 24, 2013 at 19:18

I'm familiar with the problem. One nice solution I heard about (but haven't tried myself) was an agile team that did Kanban properly (with a real physical board) and added a "principles" area where decisions like this - or at least nags about recurring pain points - could be written up ("use X if you're doing Y", "don't forget W", "our stuff now needs to work with Z"). On the physical board they'd have a good chance of being seen by someone going to move their story card to an "active" or "done" column and jogging their memory that it's something they need to bear in mind/do something about.

Of course it's diminishing returns if you have too many of them, but stuff would get from the principles area into the culture/communal knowledge/habits of the team and the board space could then be updated to be something about something else now thought to be causing more trouble.

Good example of an "information radiator" in action I think.


Records of decisions made, whether in the form of design documents or meeting transcripts, should be stored in plain UTF-8 text files within the version control system, in the same repository as the organisation's source code, so that you can maintain traceability between when a decision was made, and when it was implemented.

Ideally, the decisions/minutes & other design documents should make use of machine readable conventions such as YAML or Markdown so that reports can be generated in whatever file format is required (HTML; PDF; DOC), whilst also permitting the use of version control tools like diff, merge and blame.

Not the answer you're looking for? Browse other questions tagged or ask your own question.