The engineering notebook

Your notebook records reasoning, including results that did not work. Keep one Markdown entry per session in your own private repository. A notebook is not a polished story written after success: record predictions before testing, retain unexpected outcomes and date changes to the method.

A ten-minute documentation routine

1. Before building, write the challenge, measurable target and hypothesis. Name the changed factor, measured response and fixed conditions.
2. During testing, enter every attempted trial into a raw CSV. Put units in column names. Record condition, source revision and failure/stop reason.
3. After testing, calculate derived quantities in a separate analysis file. Link plots to their underlying dataset.
4. Finish with observations, interpretation, uncertainty, conclusion and one specific next test. Review the diff and commit the intended files.

Standard entry template

# YYYY-MM-DD — Challenge title
- Date and session:
- Challenge and measurable success criterion:
- Hypothesis and predicted result:
- Design sketch and alternatives:
- Equipment, firmware, code commit and units:
- Method and controlled variables:
- Raw measurements: link CSV; retain every trial
- Plots: axes, units, captions and data source
- Observations: what was measured or seen
- Interpretation: what you think it means
- Error and uncertainty: resolution, bias, variation, limitations
- Conclusion: supported, contradicted or inconclusive
- Next steps: one testable change
- Sources and AI assistance: what was used and verified

Download the notebook template. Save it as notebook/w05-s3.md, for example. Blank template fields are prompts for your own evidence; the course does not provide fabricated measurements to fill them.

Worked entry — fictional, not collected data

Date/session: example, Week 5 Experiment. Challenge: measure repeatability of a fixed pulse. Hypothesis: five distances will remain within ±2 cm of the pilot target of 20 cm.

Design: same robot, mat, start guide, command and 0.5 s pulse; distance measured after stopping. Alternatives: use encoder distance, but retain the ruler as independent truth. Method: reset pose, arm, pulse, stop, measure, record; repeat five times. The operator can abort at any time.

Raw source: this table is illustrative; an actual notebook links ../data/w05-fixed-pulse.csv. Plot: trial number on x, distance in metres on y, pilot target and tolerance marked. Never label a fictional plot as a measured result.

Observations: mean 0.20 m; range 0.02 m; five values fall in the predeclared 0.18–0.22 m band. Interpretation: this procedure appears repeatable for these five trials. Slip could contribute, but the experiment did not isolate it.

Uncertainty: a ruler with 1 mm marks does not guarantee 1 mm endpoint accuracy. Defining the robot centre, angle and operator placement introduces additional uncertainty. Five trials do not establish performance on other surfaces or battery states.

Conclusion: the illustrative results support the stated small-batch hypothesis. Next test: alternate five guided and five unguided starts at the same command/duration to test whether setup changes spread. Source/AI record: list any code explanation used and how it was checked.

Observation versus interpretation

“Left encoder increased 120 counts” is an observation. “The left wheel travelled exactly 12 cm” uses a calibration assumption. “The robot veered because the floor was slippery” is a causal interpretation needing a controlled comparison. Use separate paragraphs so a future reader can challenge the explanation without losing the data.

Raw and derived files

Keep raw files unchanged after collection. Correct a transcription error with a recorded correction, rather than silently overwriting it. Save derived speed/error tables elsewhere. Preserve missing values as missing and give the reason; zero is a physical value, not a universal missing marker. Store aborted runs with their stop reason. Use relative file links so the notebook survives a move or clean clone.

Plots that make claims inspectable

Every plot needs labelled axes, units, caption, conditions, source dataset and version. Show individual points for a small sample. Use the same axes when comparing controllers. Report failures beside an arrival-error plot, because the plot of successful arrivals alone excludes unsuccessful missions. See the math primer for calculations and the testing guide for fair comparisons.

Weekly report and review

Use the experiment-report template. Summarize the question, model, procedure, full trial table, comparison, limitations and decision. Link session entries instead of duplicating them. A peer should find the tested code, reconstruct one calculation and understand what remains unknown. See portfolio examples and assessment for milestones and the final defence.