The most painfully obvious reason to keep a development journal came to me at work today. One of the major reasons to keep a lab journal is to log the experiments you run. This is so future you and others can read about how you did things and what results there were so that standards can be upheld and test can be rerun if needed. When I wrote my last post—and this has been baffling me all day—it did not occur to me that experiments = tests. When you are testing code write down what you did and what the results were. If you do that you won’t have to worry as much about forgetting what you tested, forgetting the results of your tests, convincing a coworker that you tested something, and convincing a coworker of the results of your tests. Future you will thank you.
Inspired by scientific lab journals I have decided to start a development journal. This may be considered a waste of time given programs being fairly easy to reproduce, comments acting as documentation within code, and source code tools providing a history which can be used to prove originality. I believe it can have other uses that will make it a valuable use of time.
One straightforward benefit is taking the extra time to consider decisions. Notes describing problems and notes describing solutions can both benefit. When bug fixing the act of listing all of the known conditions and factors may uncover the problem. Writing down what was done and the justification for doing it creates an internal dialogue which opens the doors for self evaluation.This evaluation gives time to analyze whether a solution solves the problem and whether another solution may solve the problem in a way that could be considered better. In the few days I have been keeping a development journal I have noticed a change in the design of the projects I have been working on towards a more structured use of design patterns. This is not enough to say the code I am writing is better but I consider it promising enough to continue with the journal.
Another potential benefit is the switch from keyboard, mouse, and screen to pen and paper providing a boast to creativity. This mental state shift will allow the problem to be looked at differently. Writing down the problem gives times to restate the problem which can also lead to being more creative. Sadly I can’t seem to find any evidence for this point so I’m not sure how strong of a benefit this is.
There are other benefits as well. Paper is a particularly good medium for drawing out UML, flow, state, and other forms of diagrams. It provides a place to leave more justification for why something was done than what is typically put into comments.
Even though writing out a journal is likely to slow down the development process some I believe the potential for better code outweigh this risk. I will aim to write another post when I have more anecdotal information. Also, I’ll edit this post if I can think of any other potential benefits.
While entertaining the idea of writing a development journal I read several posts about lab journals to determine how to go about things. Of particular aid was Maintaining a laboratory notebook by Colin Purrington. Unfortunately the world of science and computer science are different enough to make much of the advice inapplicable. There will be much to learn regarding what belongs and what does not but I believe there are a few things that carry over very well or seem useful enough to act as a starting point.
If you’re going to be spending a decent amount of time writing you might as well enjoy the process. Therefore, buying a good quality notebook and pen seem like appropriate first steps.
For a notebook I decided on a Kokuyo A5 B (the one with 28 lines) notebook with one of the A5 covers. The notebook+cover was more expensive than other nice notebooks such as a Leuchtturm (my second choice) but the cost of replacement notebooks is much cheaper. I personally wanted a notebook with faint or no lines. My Kokuyo notebook has faint blue lines, the Leuchtturn notebook I was looking at had dots instead of a being boxed or lined, and a notebook such as Whitelines notebooks may be work looking into. I would advice against getting notebooks with spiral bounding, perforated pages, or using a 3 ring binder as you really shouldn’t be removing pages from the notebook. I would also advise against using a 3 ring binder as you shouldn’t be adding pages to the journal. I would advise you to get a good quality notebook with glued or threaded binding. You want your notebook to last and be a potential reference.
Pens are probably much more about personal preference though I would say you should definitely be using a pen. Knowing you are about to write something down that you can’t erase, in a notebook that you won’t remove pages from, that someone else might read, gives an added bit of deliberation before you commit thought to paper. A nice pen also writes better and lasts a lot longer on the paper. I am currently using a fine tipped fountain pen because I enjoy writing with it. I would also be happy with a 0.38mm G2 gel rollerball or a 0.3mm Micron. Point here is to write with what you like to write with. You’re going to be doing a lot of it so you should enjoy the process.
To prepare your notebook you should leave a few pages in the front for a table of contents. If your pages are not already numbered you should number the remaining pages of the book. Put your name on the cover or the first page as well as the start of the date range the notebook will cover.
I am not completely sure of the best way to add entries into the book. It makes since to title projects as that gives a name for the table of contents and ties together multiple entries on the same topic. A date should be given to each topic. If a topic continues for multiple days without another topic interrupting it then you should probably put a date in the notebook for the start of that days notes. I would also think it generally better to not put multiple topics on a page though leaving sufficient space between topics on a page may make it clear enough that there are different topics.
This is all that I currently know and speculate about a development journal. I will provide further posts in the future as I discover more.