1. 14

  2. 5

    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.

    How I wrote the notebook

    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
    • 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.

    Uses of the notebook

    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.

    1. 1

      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.

    2. 1

      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).