Lab Notebooks

What wet-lab chemistry can teach software engineers

July 20, 2020

In college I worked as a developer in several science labs, including a chemistry lab. Even us computational folks were told to keep lab notebooks, and the protocols for your lab notebook were quite strict. At the time, I was not very good at using my notebook (or at doing the science, frankly). Over the intervening years, I’ve come to understand and value what they were for; and now I keep lab books for almost all my software engineering work.

What’s a lab notebook?

It’s a disciplined record of what you do and think each day.

One of the hardest things about software engineering is that, while it’s often possible to understand the code you committed, it’s usually impossible to see all the things you tried first, that didn’t work. This is a trap for other developers, and even your future self, where a seemingly better solution gets tried again and again, and each time the same problem arises. But since the failure never gets committed, no record of the attempt is left. I suspect most experienced developers can remember a time where their memory saved a team hours or even weeks of work, simply by saying “ah, we tried [clever solution] a few years ago, but ran into problems X, Y, and Z. So we’d need to solve those problems before we try again.”

A lab notebook takes that kind of information out of your memory and puts it somewhere safe and permanent.

Also, too many developers rely on their working memory, and end up burning out because they are afraid to leave a problem halfway. If the entire plan of attack exists only in your head, taking a lunch break can be disastrous.

A lab notebook makes it safe to stop work at any time.

As a consultant, it’s perfectly possible for old client to call me up and ask for advice, or an explanation of something I did for them. It’s no fun for anyone to say “sorry, I’ve worked on 5 other client projects since then, I have no memory of what I was doing.” On the other hand, it feels great to roll over to my bookshelf, grab the notebook associated with that client, and find a detailed explanation of what I did and why.

In a meeting, writing in a notebook is socially more graceful than typing on a laptop. On a laptop, you might be answering email, or on facebook, or backchannel-chatting.

A paper notebook is a way of signalling you’re present and listening.

Finally, and least compelling, the Eudaimonia Machine office design gets some attention from design and tech people every few months. Few people really discuss what goes in the library/archive room of the machine. One answer: your old lab notebooks.

What are the rules?

I said there was a lot of discipline associated with a lab notebook. This is in part for forensics. If plagiarism/data falsification/ethics/etc concerns arise over some scientist’s research, the lab notebook can be valuable exonerating evidence — but only if the discipline is kept.

Software engineering doesn’t have quite the same forensic constraints, but the same disciplines have nevertheless been valuable for me. Here are some of the major points:

  • Always in pen.

    Your goal is not to preserve the outcome of your thoughts — that’s your code. Your goal is to preserve the process of your thoughts. So no erasing, no blacking out. You can put a single line through anything spelled or written incorrectly.

  • Always during

    Write down what the problem is, what you’re about to do, and what you expect the result to be. Treat your work as an experiment! This is especially valuable for junior developers who are still in a “try everything until something works” frame of mind. Forcing yourself to hypothesize what’s actually wrong is really valuable; and there’s nothing wrong with expecting a negative result (“I don’t think the problem is X, but it’s easy to prove it, so…”)

    If during the actual process, you deviate from your written plan, write down the deviation, and why you’re doing so.

    Don’t wait until after you’re “done” — because “done” might mean six hours from now.

  • Always forward.

    If you write something on Monday and realize you were wrong on Tuesday, write the correction in Tuesday’s entry. This is a lab journal — from the French “daily”. If you had a misconception, you want a record of that, as well as a record of why you were wrong. You can (and should) add a small note to the original entry pointing to the page where you correct yourself — but don’t obscure what you originally wrote.

  • Keep a table of contents

    The first pages of your notebook should be a table of contents; with a few words summarizing what is on each page. Make it easy to answer questions about what you did, and why, even if years have passed.

  • Keep a habit

    At the start of each day, read yesterday’s pages. Write down what you intend to do today. At the end of each day, read through today’s pages, and add an entry to your table of contents.

  • Summarize when necessary

    If you’ve spent a messy week going round in circles, and you lab notebook has become hard to follow, feel free to take a page to summarize what you’ve learned and where you ended up. Flag it specially in your table of contents.

  • Store safely

    At the end of a project, label the spine of your notebook, and store it safely with your others. It should be easy to access if questions ever come up.

These aren’t all the guidelines — pick a research university and I guarantee they’ll have some multi-page document explaining all the protocols surrounding your lab notebook — but these are the ones that have stuck with me.

What notebook should I use?

I use full-size gridded notebooks from Vela. They’re made locally, and specifically designed for use as lab notebooks, so they have page numbers, page titles and dates, tables of contents, and so on all built-in; they make keeping the above disciplines easy. Vela also sell notebooks covered in material designed for use in wet labs; if you’re a clumsy person, an extra few dollars can make your coffee spill no big deal.

They’re expensive, but I rarely use more than one per client, and I’m confident they’ve been worth it every time.

(I have no relationship to Vela; I-just-think-theyre-neat.gif)

Isn’t this just a bullet journal? Isn’t this just a planner? Etc.

Sure, do whatever works for you. I call it a lab notebook.