During my recent 6-month co-op (during college), I took a “lab notebook” containing things similar to what the article describes. I had a notebook for each of 3 projects that I was working on solo. Here is some information about my notebook for one of those projects, to help you decide whether you would find keeping a notebook worth it.

It was a single file – an OmniOutliner document called “[project name] tasks”. That means it was an interactive outline – I could expand and collapse sub-items, hoist any item to the top level temporarily, and highlight items by selecting them. I had four top-level categories:

• current
• unsorted
• on hold
• archived

“current” was the one or few tasks I was in the middle of right now. “on hold” were the tasks I was deferring to later. “archived” were the tasks I had already completed and just kept the notes for. “unsorted” contained just one thing, “links” – I wasn’t sure where to put it. “links” had a bunch of links to documentation, tutorials, and relevant blog posts that I thought I might need.

Here are two example tasks within the “archived” category, with all bullets expanded:

• getting the deployment on the Ubuntu computer working
  • Gist (GitHub) – Ubuntu command to install Ruby standard libraries
  • Google search – “unix shebang bundle exec”
  • how to run the script periodically
    • hourly is good enough, since that’s easy
    • make run hourly by hard-linking to /etc/cron.hourly
    • but what should I link there?
    • considerations
      • the #! line says ruby, but I need bundle exec ruby
        • that is apparently impossible to run, so I won’t do it with a shebang line
      • I’m not sure if push-….rb will run in the correct version of Ruby, too, because rbenv might rely on what the current directory is
      • bundle exec requires that you are in the correct directory first
• Why aren’t the *_html_explanation methods being found?
  • When are those methods trying to be called? It should be after the module is included, not from the module itself.
    • It’s after the definition of UpdateStatusHtmlGenerator, according to a trace statement.
  • It was because I had forgotten that I was in the middle of rewriting them from self.foo to class << self syntax, so they were instance methods when they should have been class methods.

Here’s a screenshot of those two tasks in OmniOutliner.

Most of the time, I wrote notes in chronological order. A few items had sections that I kept up to date, such as when I was comparing multiple choices and noting their advantages and disadvantages as I found them.

And yes, my notes really were formatted that richly. I had custom text styles for code, file paths, and URLs, and I embedded links in my text.

I was definitely glad I had my notes at times, but I haven’t really analyzed whether they were worth the time I spent writing it. Nonetheless, here’s a list of some things I used the notes for:

• remembering where I left a task in progress, if I leave it for some time in the middle
  • this included going up the stack of tasks – when I finished a subtask, I could remember the bigger task I was working towards
  • This makes it easier to work when you’re not at your best – if you’re distractingly tired or hungry, just do what your notes tell you to do, step by step, and you’ll get the task done. For instance, if you’ve written “why is this method not getting called?”, just mindlessly iterate through each possibility, writing them down and testing them, until you find the answer.
• explaining my decisions for organization of the code and use of the software during a meeting
• remembering what file to look in to find some certain piece of code I worked on earlier
• satisfying my compulsive hoarding of information – I could be sure that none of what I found or decided would be lost

I may have used it for other things that I can’t remember right now. I may also use it for other things in the future, if I look through it again.

I feel like inline comments plus early/often commits to version control would almost be better than a lab notebook. Perhaps this could also be supplemented by a blog or similar to summarize big-picture ideas or discoveries.

In any case, I definitely agree with the higher-level point that we as developers can do better at documenting what we do. I think this is important for productivity (e.g. quickly figuring out where you left off), personal growth (e.g. forcing yourself to think more about the process instead of just banging on the keyboard), and posterity (e.g. sharing what you learn with others).