Sam writes about his learning journey of keeping lab notebooks to keep track of his work.
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.
see: Documentation
This is what I also talk about in Contemporary Documentation (talk) as the reason for writing down the discussions and decisions, even those that were negative and did not lead to work being done.
A lab notebook makes it safe to stop work at any time.
This is helpful for context switches, weekends, holidays and sick leaves as you can always get back to figuring out where you were and what you were doing and thinking about when the work was disturbed.
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.
see: Taking notes
The rules
-
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 anyt- hing 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.