Why you should keep a development journal

Photo by Kyson Dana on Unsplash

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

After a quick review I go, “this would be so much cleaner and faster if I 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 what led me down this less elegant path in the first place was a shortcoming in some 3rd party library or a restriction in the production environment.

And, if I wouldn’t have discarded my refactorings, the risk of having introduced new bugs.

Capture the purpose behind all decisions

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 reasoning 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.

Dear diary

This is the place where the team can scribble down why they discarded a certain architecture in favour 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, e.g. 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

Over time, this tends to be the kind of information that only exist 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 people 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. Or to use a metaphor: if the regular documentation is a classic SQL Server database that shows the current state, the development journal is more of an event store.

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 a simple blog.

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.

Founder of Flowmine: https://flowmine.com. Building SaaS products and consulting in web development, solution architecture, and agile transformations.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store