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” 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:
bundle exec ruby
class << self
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:
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.
Great to see other fans of OmniOutliner here, it’s a fantastic piece of software and I think software engineers can learn a lot from getting a deep understanding of outliners. I’m personally taking an internship over the summer break right now so I’m going to give this idea a try.
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).