Best Practice: Keeping an Electronic Notebook

My electronic notebook saved me today. I had a technical problem here at work, involving some old internal software. I vaguely remember using this software, but instead of rummaging through old e-mails or polling my co-workers I grepped my electronic notebook. I was able to find notes from the first time I used this software nearly two years ago. Rereading these put enough details into my head to be back "up to speed." I felt pretty smug. Electronic notebooks are my personal "best practice."

So what are these electronic notebooks? They're text files. One text file for every working day. (Each file is named MMDDYY.txt.) Each text file is a running log for what I was doing at the computer that day. This is what my electronic notebook directory looks like:

Most of what I capture in these files are arcane command lines that I happen to concoct. Here's one from from 2004 (September 30, to be precise), using sed to break up a file with no line breaks on the string "eor".

Another kind of entry that I make are errors that I see, and what I did to resolve them. Here's a C++ compilation error for some code I was trying out (to help with my Tetris project):

The resolution? In my notes I wrote "I needed to make this a STATIC method!" (Translation: In my Picture.h file, I changed "int max(int, int)" to "static int max(int, int)").

My notebook files contain anything and everything that I might want to remember or lookup in the future. It contains people's names, phone numbers, conference bridge lines, WebEx URLs, directory paths, useful websites, book titles, Java CLASSPATHs and (of course) snippets of code. The one nod to "structure" is that for every entry in a file, I separate it with a "*", and a brief message. It's a headline for the notebook entry. Here's the single entry for my first day at work at my new job:

Here's the second day (excerpted):

Separating entries in this manner allows me to glance at a single day's file to see what I might have tackled. Add client names if you're a consultant or sales engineer. Add case numbers if you're in technical support. This ability to produce "sections" adds just enough structure to make things useful. (And as a billable consultant, this sometimes helps with the time keeping.)

The habit of writing notes like these started with my second job out of college. I was doing lots of SQL and UNIX work, and nothing was well documented. That work was perfect for this practice. Reviewing the daily entries reinforced what I was doing. Reviewing the issues and how I got out of them paid off when the same error occurred the next time, whether it was one day later, one week later, or even many years later.

You might put all of these notebook files into a database or search engine, but I wouldn't go through too much trouble. As long as they're textual, you can grab the content using simple tools. The key is simplicity: simple to enter, simple to look up.

I have over 1400 of these files for my current job. This is my raw knowledgebase, a rough copy of what went through my brain. When I think of all the daily technical habits I have, this is the one with the best dividends.