What a research notebook is for

Laboratory scientists learn early that an experiment not written down did not happen. The bound notebook, with numbered pages and dated entries in ink, is one of the oldest instruments of experimental science, and it survives because it does something no other record does: it captures what the experimenter knew and intended at the moment of acting.

Computational work has inherited the experiments but not, in most places, the notebook. A modern analysis leaves behind a repository full of code, a directory full of outputs, and perhaps a commit history. It is easy to believe that this is a complete record. It is a record of what was done. It is almost never a record of why.

Code is a precise description of a procedure. It says which model was fitted, with which options, to which file. It does not say that the first model was fitted too and abandoned, that the outlier at row 4,312 was removed because the instrument log showed a fault, or that the threshold of 0.05 was chosen before looking at the data rather than after. Each of these facts changes how a result should be read, and none of them can be recovered from the final state of a repository.

Commit messages help, and good ones are a partial notebook. But a commit records a change to files, and many of the decisions that matter in research change no file at all: the decision not to pursue an idea, the observation that a plot looked wrong, the hypothesis held before a run. A commit history is shaped by what the code needed, not by what the reasoning needed.

The research notebook fills that gap. Its purpose is narrower than a diary and broader than documentation: it keeps the reasons for decisions, written down while they are still reasons rather than reconstructions.

The single most useful habit is to write down what you expect before you run something. One or two sentences are enough: what you are about to try, why, and what result would surprise you.

The value of this is not ceremony. A prediction written in advance is the only reliable defence against the quiet rewriting of expectations that happens once a result is on the screen. Every analyst knows the feeling of a result that seems obvious in hindsight; the notebook shows whether it was obvious in foresight. Over months, the record of predictions also shows where your intuition is reliable and where it is not, which is worth knowing.

A prediction also makes a failed run informative. “The model did not converge” is a fact. “I expected convergence because the previous run with a smaller step size did, so the step size is probably too large for the new data” is a step towards the next decision.

Entries should be short, dated, and written in plain language. They do not need to be polished; they need to be honest and findable. A typical entry might read:

14 March. Refitting the seasonal model with the corrected holiday calendar. Expect the residual spike in late December to disappear; if it remains, the spike is not a calendar effect. Data version: checksums as of 12 March. Commit 4e1a9c2.

Later. Spike is smaller but still there, about a third of its previous size. Calendar explains part of it. Next: check whether the remaining spike coincides with the change in the reporting system in December.

Notice what the entry links: a date, a data version, a commit. Those links are what turn a page of prose into part of the scientific record. Without them, a note that says “the corrected model looked better” cannot be connected to anything that can be rerun.

A notebook should point to artefacts, not contain them. Results, figures, and data live where they are produced and versioned; the notebook records which version was examined and what was concluded. Copying a figure into the notebook freezes one picture of a moving analysis, and before long the picture and the code disagree.

The useful links are few:

• the commit of the code that was run;
• an identifier for the data, such as a checksum or a dated snapshot;
• the location of the output that was examined;
• the seed of any random step.

With those four, a later reader can reconstruct the situation in which a decision was made. Practical guides to organizing computational projects have long recommended a dated notebook kept alongside the code for exactly this reason.¹

The temptation, when a notebook is shared, is to tidy it: to remove the approaches that failed and present the path to the result as if it had been straight. Resist it. Dead ends are the most valuable part of a notebook, for two reasons.

First, they prevent repetition. An idea that failed for a good reason will occur again, to you or to a colleague, and the notebook is the only place where the reason is recorded. Second, they are part of the evidence. A result found after trying twenty specifications means something different from a result found on the first attempt, and the reader of a paper deserves to know which it was. The notebook is where that information lives until it is needed.

An entry is never edited after the fact. If a later entry corrects an earlier one, it says so and links back. The value of the record depends on its being contemporaneous, and a notebook that is silently revised is no longer evidence of anything.

Most notebooks are never read by anyone but their author, and that is enough to justify them. The author six months later is, in every practical sense, a different person: someone with the same skills and none of the context. That reader needs to know what was tried, what was concluded, and why, and the only way to give it to them is to write it down at the time.

Rules for laboratory notebooks in computational work tend to converge on a few principles: record everything that is needed to understand a result, date every entry, link entries to the code and data, and never rewrite history.² None of them requires special software. A plain text file per project, in the same repository as the code, with a heading for each day, satisfies all of them.

A research notebook is not a place for results to be presented, and it is not a project plan. It is not a substitute for documentation, which explains how to use what was built, or for a paper, which argues for what was found. Each of those documents is written for a reader with a purpose, after the fact, and each is improved by being selective.

The notebook is the opposite: written for no one in particular, at the time, without selection. That is what makes it trustworthy, and it is what makes the other documents possible. A paper’s methods section, written months after the work, is only as accurate as the record it is written from.

The best argument for keeping one is the first time you need it: when a reviewer asks why a sample was excluded, or a colleague asks whether you tried the obvious alternative, and the answer is on a dated page, with a link to the commit that settles it.