On Logbooks

My friend, Michael T. Richter, presented me with a nice concept from engineering. The logbook. The concept is extremely simple: you keep a log of your work, so you can refer back to it later. Yet, there are relatively few in Computer Science who does that, which is a sad state of affairs.

The odd thing is that most computer scientists do know the importance of logging in an application. You see these elaborate logging frameworks that can log at different log levels, can forward logs between machines and so on. Yet—it looks like the CS people forgot that the same logging could apply to your own work.

My Log comprises two files. One for work and one for personal projects. In each file, I keep track of dates. The file is pure text, though I use utf-8 encoding, so I have access to full Unicode, which I exploit fully. I have the following in the file in the acme(1) editor:

<date +%Y-%m-%d

which can be run to enter the current date at the cursor position. I tend to jot down the projects that are in progress. My log is not a TODO list! I’d rather track stuff I have done than stuff I don’t have time to do. Having a log gives me some immediate benefits:

I can run grep on old entries. This is tremendously efficient. I often write down shell-oneliners, R scripts, hostnames too volatile for .ssh/config, results from benchmarks, test failures, meeting outcomes and so on. I can find old stuff as long as I remember that I wrote it down at some point in time. I also keep links to papers, Issues I am working on, source files and so on. My editor of choice, acme(1), allows one to write file:/REGEX to open a file and then perform a search within that file based on the regular expression I give. In effect, I have full history tracking.
I can answer the question ``What did you do two weeks ago?'' with ease. It also means I can gather knowledge about what kind of work I am currently doing and for what purpose.
The log acts as a tool for improving the process. By keeping track of what is being done, I can look back and see what can be done better. This allows me to run an iterative quality improvement process on my development.
The log allows me to use the “Hemmingway trick”, which is leaving a sentence before it is done and finished. It is then easier to go back and pick up from where you left. By tracking what is currently in progress, I have an easier time entering flow again on the piece of code I am working on. Switching ``context'' is also way easier. Since I can write down where I am currently on one part and then switch to another part.
Since the log tracks stuff in progress, I can quickly figure out if I am starting too many new projects and not finishing any of them.
The log allows me to clear my brain once in a while since it has been documented elsewhere.
It is way easier to have focus with a log of what is being done, vastly improving efficiency and output.

Personally, I think the most important part is that this has vastly improved my process. Especially when hunting for bugs. I tend to write down what I know and what hypothesis I have. Then I try to devise some experiment that can cut through the hypothesis and cleave up the possibilities. Bug finding becomes much faster when you approach it like this.

Another part of the process which also has improved is the approach to writing new code:

I try to document the purpose of the new piece of code. That way, I make sure I know why it is important to implement this part—and I document that for future reference.
I often write down how hard I think the code is to complete. This gives me a benefit later when I can go back and see if I was right or wrong with the estimate.
If we had multiple solutions, that is documented.
If a test comes up with a surprising result, that is documented.

As a consequence, you do less work and better quality. The concept of the logbook is hereby passed on to the reader.