Development Journal

The Value of a Development Journal

Each and every develoment effort is also a learning experience. How many times have you "figured" something out through a development project and subsequently been asked about it, only to respond, "hmmm, I know I did that in project X but can't seem to remember how anymore!"

Its for that exact reason that I believe in using a development journal. It doesn't have to be complicated, just a text document (I prefer an eletronic format) that tracks your progress with date time stamps. The other key value of the development journal is that it fosters the "test first" approach. You write down what you are going to do, and then you document how you did it. Development is about solving problems and the best way to solve problems is to define them adequately first. Sure things might change as you learn more either about how to develop or what you are developing but these events just go into the journal as they happen.

A development journal does take some effort. So what value does it add? Why bother at all? Here's a list of some of things it can provide:

It improves your thought process

The simple of act of writing down what you are going to do before coding it greatly improves your thought process, and gives you a better problem solving approach.

It gives you some history

This "history" is of your thought process (allowing you to get the "Ah! that's why I did that" response) and a history of your code in plain english.

It documents approaches and solutions

If you ever need to go back to figure out how you did something, the development journal is where to start. This is a *lot* easier than reading through old code, especially if it wasn't written all that well.

It gives you a place to store notes

Through a development effort you'll want to keep notes. Notes on what you need to do, what you have been told, why things are a certain way, the development environment etc. This is a great place to put that "stuff".

It helps you with documentation

You can go through your development journal and use it as a template for any documentation. The journal should document your basic design (over time).

It helps you with testing

You should write tests for your design as you write your design. These steps will become test steps and should test the "essence" of your development effort.

How to maintain a development journal

So how do I start a development journal? Well first, subscribe to KISS (keep it simple stupid!). Make it a text file (doesn't get much easier). Use date-time stamps to track your journal in chronological order with the latest "event" at the start.

An example:

DEV_EFFORT_NAME.txt

DEVELOPMENT JOURNAL
"Development Effort Title"

{Date/Time Stamp}

...

{Date/Time Stamp}

...

Just write notes of what you did and why. The why is important, try to be as clear and concise as possible. This will help you with your regular documentation. I don't want to prescribe a format any stricter than this as it implies that there is one approach to journaling your development that's better than others. There isn't.

The main things your development journal should provide to you are:

  • A history of what you've done
  • Notes as you developed
  • Changes as you developed
  • Tests for what you developed
  • An explanation of why you developed the way you did
  • General information pertaining to the development effort

The journal will push you into a Write -> Develop -> Test -> Update cycle with your development work. You'll write what you want, develop it, test it (from the tests you wrote), and update the journal/development with changes as you find new things.

A final word of advice. Keep your development journal source controlled like any other piece of development.

Tools

An alternative to using a text file is to use a hierarchical notes organiser like The Guide. The Guide is a portable application, it allows you to insert a date/time stamp, and can organise notes by project (in a tree structure). It also has a great search, caters for attachments, allows for easy hyperlinking to web pages, files and other nodes in the tree.

This is what I personally use for managing my development work and a tool I highly recommended. It is also great for organising all kinds of personal information.

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License