On Tuesday, you rerun a test someone logged the week before: “Changed ADC divider. Looks good now.” The board on your bench has two bodge wires, the firmware folder contains three candidate builds, and the supply still remembers its previous current limit. You can see that work happened, but you cannot tell which exact state produced the result or how to judge whether your rerun matches it.

That is the gap a reproducible engineering notebook entry should close. It is not just a diary of activity, and it is not the same thing as a polished README. Its job is narrower: capture enough context, procedure, evidence, and interpretation that another competent person can repeat the work and decide whether they got a meaningfully similar result.

The structure below is an editorial recommendation, not a formal standard. Where measurements are involved, two source-backed ideas matter. First, NIST explains that a measured value is not really complete without an accompanying uncertainty statement (NIST TN 1297 section 2). Second, NIST describes combined standard uncertainty as the estimated standard deviation of the reported result, formed from contributing uncertainty components, with covariances when needed, commonly via the root-sum-square approach (NIST TN 1297 section 5).

What belongs in a reproducible notebook entry

A useful notebook entry lets a later reader answer five practical questions without guessing:

• What exact question was being answered?
• What exact system state was used?
• What steps produced the observation?
• What evidence was captured, in what units and with what limits?
• How should a rerun be judged: consistent, different, or inconclusive?

That reader-centered approach lines up with general documentation advice, even though a notebook entry is more specific than project docs. Write the Docs recommends explaining the problem being solved, showing a small example, and giving readers the information they need without burying them in extra material (https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/). GitHub’s README guidance similarly says a README should help visitors understand what the project is, why it matters, how to begin, and where to find help (https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes). A notebook entry applies the same principle to one run, one experiment, or one debugging session.

A suggested minimum structure:

A suggested heuristic: if a value could plausibly differ tomorrow and affect the result, record it. That includes firmware hash, branch name, calibration status, ambient conditions, input file versions, jumper positions, feature flags, and instrument settings.

Separate evidence from interpretation

Many notebook entries fail because they are written as memory aids. A reproducible entry should behave more like a small experiment package.

One practical way to do that is to split the entry into four layers:

• Observed: what was measured, logged, or seen.
• Derived: what was calculated from those observations.
• Assumed: what was treated as fixed, negligible, or modeled.
• Concluded: what the evidence supports.

This matters because uncertainty is not the same thing as error. NIST distinguishes uncertainty components evaluated statistically, called Type A, from those evaluated by other information sources, called Type B (https://www.nist.gov/pml/nist-technical-note-1297/nist-tn-1297-2-classification-components-uncertainty). NIST also notes that the familiar “random” versus “systematic” vocabulary does not map neatly onto that classification in every case (https://www.nist.gov/pml/nist-technical-note-1297/nist-tn-1297-2-classification-components-uncertainty).

For notebook writing, that translates into a few practical habits:

• If you estimated spread from repeated measurements, say how many repeats you used.
• If you used instrument resolution, datasheet tolerances, calibration records, or engineering judgment, label those as non-statistical inputs.
• If you applied a correction for an identified offset or bias, record both the correction and the uncertainty attached to that correction. NIST treats the uncertainty of the correction as distinct from the original error source (https://www.nist.gov/pml/nist-technical-note-1297/nist-tn-1297-5-combined-standard-uncertainty).

A compact template:

Observed:
Derived:
Assumed:
Concluded:

That small separation prevents a common failure mode: turning a rough indication into a stronger claim than the evidence can carry.

Fully worked example: a hypothetical notebook entry

The example below is hypothetical and uses synthetic data. It is included as a reproducible pattern, not as a report of real testing.

Scenario

Task: determine whether changing a resistor in a voltage divider moves an ADC input into a target range when the input source is nominally 12 V.

Example entry

Entry ID: EN-2026-11-04-ADC-01 Date/time: 2026-11-04 14:00–15:10 local Objective: Check whether replacing R2 = 10.0 kΩ with R2 = 11.0 kΩ moves the ADC node into the target band 2.70 V to 2.80 V at nominal Vin = 12.00 V.

Context

• Board: Power-monitor prototype rev C
• Schematic version: pm-revc-sch-7.pdf
• Firmware commit: 8f2c1d4
• ADC reference setting: internal 3.300 V nominal
• Bench supply setting: 12.00 V display, 0.50 A current limit
• DMM: 6.5-digit meter
• Ambient assumption: 23 ± 2 °C estimated, not actively controlled

Model

Vadc = Vin * R2 / (R1 + R2)

with fixed R1 = 39.0 kΩ.

Predicted values from nominal resistor values

• Before change: Vadc = 12.00 * 10.0 / (39.0 + 10.0) = 2.449 V
• After change: Vadc = 12.00 * 11.0 / (39.0 + 11.0) = 2.640 V

Observation about the model

Even before measuring, the nominal post-change prediction is below the stated target band. That means the test is useful, but it should also trigger a review of whether the target or resistor choice is wrong.

Procedure

• Power off supply and disconnect board.
• Photograph installed R2 and note board serial.
• Replace R2 with labeled 11.0 kΩ part from lot SYN-11K-A.
• Inspect solder joints at 5× magnification.
• Reconnect board to supply with no external load.
• Wait 60 s before recording data. This 60 s wait is a suggested heuristic, not a source-backed universal settling time.
• Record five readings of Vin and five readings of Vadc at 10 s intervals.
• Compute the mean and sample standard deviation for Vadc.
• Treat the repeated readings as independent for this hypothetical example and use the standard uncertainty of the mean as the Type A term.
• Estimate a Type B term from DMM resolution using a rectangular-distribution assumption.
• Combine the Type A and Type B terms by root-sum-square, following NIST’s combined standard uncertainty framework when the components are treated as independent (https://www.nist.gov/pml/nist-technical-note-1297/nist-tn-1297-5-combined-standard-uncertainty).

Raw observations (synthetic data)

• Vin in V: 12.002, 12.001, 12.003, 12.001, 12.002
• Vadc in V: 2.641, 2.640, 2.642, 2.641, 2.640

Derived values

Mean Vin = 12.0018 V Mean Vadc = 2.6408 V

Sample standard deviation of Vadc:

s = sqrt(sum((xi - x̄)^2)/(n-1)) ≈ 0.00084 V

Type A standard uncertainty of the mean, under the stated independence assumption:

uA = s / sqrt(5) ≈ 0.00038 V

Type B standard uncertainty from a hypothetical DMM resolution half-width of 0.0005 V, modeled as rectangular:

uB = 0.0005 / sqrt(3) ≈ 0.00029 V

Combined standard uncertainty:

uc = sqrt(uA^2 + uB^2)
   = sqrt(0.00038^2 + 0.00029^2)
   ≈ 0.00048 V

Reported result

Vadc = 2.6408 ± 0.0005 V

Here the ± 0.0005 V value is the rounded combined standard uncertainty.

Interpretation

• The measured post-change result is 2.6408 V.
• The modeled pre-change nominal value was 2.449 V.
• The resistor change increased the ADC node relative to that nominal pre-change model.
• The measured post-change result is still below the stated target band 2.70 V to 2.80 V.
• The shortfall from the lower target edge is much larger than the reported uncertainty, so the mismatch is not explained by the uncertainty estimate alone.

Rerun check

A rerun is treated as consistent if:

• the documented firmware commit and board revision match,
• the installed resistor values are confirmed and recorded,
• the mean Vadc falls within 2.6408 ± 0.005 V.

That ± 0.005 V comparison window is a suggested heuristic for this example, not a universal rule.

A reusable decision procedure

If you want a repeatable method for deciding how much detail to include, use this suggested procedure.

Step 1: classify the entry

Choose the most demanding category that fits:

• Observation: what happened?
• Comparison: did A differ from B?
• Measurement: what value was estimated?
• Recipe: how can someone else rebuild or rerun it?
• Debug trace: under what exact conditions does failure occur?

If the entry mixes categories, write to the strictest one. A measurement entry, for example, also needs recipe detail.

Step 2: freeze the state

Record any dependency that could change later:

• code revision
• configuration files
• hardware revision
• instrument settings
• input datasets or test vectors
• ambient conditions, if relevant
• any applied correction factors

Step 3: choose an evidence level

These are suggested heuristics:

Step 4: define the rerun test

Add one line near the end:

A rerun counts as consistent if ______.

That sentence forces you to state what “same result” actually means.

Common mistakes, assumptions, and limits

Common mistakes

Writing only the conclusion “Fixed,” “passed,” or “looks stable” is not enough. Keep raw evidence near the conclusion.

Omitting units or sign conventions -12.3 mV is better than 12.3. If direction matters, say which direction is positive.

Hiding the exact sequence Order matters: warm-up time, reset state, load condition, and sample count can all change the result.

Mixing corrected and uncorrected values If you applied an offset correction or normalization, record both versions.

Copying precision from the instrument display Displayed digits are not automatic proof of justified precision.

Using README-style summaries as notebook entries GitHub’s guidance treats the README as a starting point for visitors, while longer and more specific material belongs elsewhere (https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes). A notebook entry should stay focused on one concrete run, not become a broad project overview.

Assumptions and limits

This article’s framework is an editorial suggestion. It is not source-backed as a universal standard.

A few limits matter:

• Reproducibility does not guarantee correctness; people can consistently reproduce a flawed setup.
• Not every task needs full uncertainty analysis; the needed detail depends on how the result will be used.
• Some work depends on tacit skill, unavailable parts, or unstable external systems; a notebook can reduce that problem, not eliminate it.
• Measurement summaries depend on assumptions, such as independence of repeated observations or adequacy of the underlying model.

A practical closing habit is to end each entry with a short verification block:

• expected invariant
• allowed comparison range
• first things to inspect if rerun differs
• location of logs, plots, photos, or scripts

If you adopt only one change, make it this: finish each notebook entry with a rerun rule. That turns the note from a private memory aid into a record another person can actually test.

AI-assisted writing with source checks and automated editorial review. Illustrative examples are identified in the guide.