Why your team should keep a development journal

Every once in a while I stumble upon some piece of code that makes my WTF-per-minute-meter go straight through the roof.

After a quick review I go, "this would have been so much cleaner and faster if I had only used the this-or-that pattern instead. No wonder this code has become a performance bottleneck; who wrote this piece of crap?"

And, of course, the individual responsible for that abomination of code is usually myself.

So in the spirit of the Boy Scout Rule, I start to refactor the code. Only to later discover that there was a shortcoming in some 3rd party library or a restriction in the production environment that led me down that less elegant path in the first place.

End result: a lot of wasted time and effort and, if I didn't discard my refactorings, the risk of having introduced new bugs.

How can we mitigate situations like this? More documentation? We already have documentation in the form a commit/check-in comments, BDD-specs, references to issues in TFS or Jira, sprint documentation, user stories, project wikis and so on. Not to mention the code itself, which, of course, is self-documenting. :-)

Shouldn't that be enough? Well, no.

The problem with this kind of documentation is that it only captures the WHAT and HOW, but not so much the WHY. Sure, fine-grained commits that tell a story about the code can go a long way, especially together with a good ALM tool, but it can be pretty hard to discern intent from that.

What we need is something that describes the rationale behind the decisions, in a broader context. Something that lets developers and architects capture their thoughts in an informal and easy to consume format. And the proper tool for that is a development journal.

This is the place where the team can scribble down why they discarded a certain architecture in favor of another, or why a seemingly bad solution is justified. Other examples of stuff that should go into the development journal:

• Thoughts on implementations and reasoning behind the choices made
• Elaborations on pros and cons with a particular solution to a problem
• Political info, for instance why it was so important that a feature had to be crammed into that sprint
• Why we chose these particular 3rd party frameworks and tools
• Why the things we are working on at the moment is a priority

In short: track the WHY behind every decision, big or small.

Over time, this tends to be the kind of information that only exists in the minds of the team members that have been on the team (or with the company) from the beginning. Needless to say, if one of these key persons decides to quit unexpectedly, it can lead to huge problems down the road.

The journal should be easy to read and give a clear picture of why we have ended up with the solution we have.

To use a metaphor: if the regular documentation is a classic SQL Server database that shows the current state, the development log is more of an event store that shows all the twists and turns along the way.

So what tool should we use for the journal? I have used Word files, Google documents and OneNote for my personal development projects. For teams, the preferable solution is to use something that is easy to use collaboratively, as a simple blog or wiki.

The important thing is not the tool itself, but to actually establish the habit of continuous capturing of the thinking process.

Keeping a development journal is a great way of making sure that we continuously capture the reasoning behind the decisions we make, and those project development journals should be an important part of every company's structural capital.