Documentation as reproducible evidence
Package requirements, decisions, interfaces, versions, and measured evidence so another builder can reproduce a result and challenge its limits.
- Produce a compact build packet that separates requirements, calculations, expected behavior, measurements, anomalies, and unresolved risks.
Related study — optional context
Understand
The working idea
A build is shareable when another person can understand what was attempted, reconstruct the relevant configuration, and distinguish evidence from belief. Photos and polished prose help, but they do not replace part identity, firmware version, wiring, parameters, units, procedure, and raw observations. Documentation is part of the technical interface between today’s builder and tomorrow’s debugger.
A useful packet starts with scope and a testable requirement: “stop the restrained wheels within 150 ms of command loss,” not “make it safe.” It includes an architecture diagram, bill of materials with exact manufacturer/model where known, schematic or pin table, mechanical dimensions, software revision, setup commands, calibration, and test records. Each record pairs expected and actual results. A result such as 112 ms needs conditions, sample count, instrument resolution, and links to logs; it is not universal certification.
Decision records preserve alternatives and reasons. Choosing a 330 Ω LED resistor should show supply, assumed forward voltage, target current, calculation, and verification. Interface tables name units, frames, rates, valid ranges, timeouts, and fault behavior. For source sharing, pin dependencies and versions rather than saying “install the usual library.” Use portable formats and relative links, while keeping raw machine-readable data beside plots.
A common misconception is that more documentation means more reproducibility. Hundreds of unlabeled screenshots can bury the one configuration that matters. Another failure is editing out unsuccessful trials, which prevents others from understanding variability and false starts. Include anomalies, deviations, and unknowns explicitly. Do not invent purchase availability, measurements, or evidence to complete a template. Redact credentials and personal information, check licenses before redistributing third-party material, and identify bench analogues honestly: a small blower experiment is not a certified vacuum cleaner, and a model vehicle is not roadworthy.
Follow the reasoning
Worked example
Five watchdog trials measure 108, 111, 109, 115, and 112 ms from last command to zero output. Summarize the evidence against a 150 ms requirement without overstating it.
- 1
Mean = (108 + 111 + 109 + 115 + 112) / 5 = 111 ms.
- 2
Observed minimum is 108 ms and maximum is 115 ms, so observed range is 7 ms.
- 3
All five observed trials are below 150 ms, with 35 ms margin from the worst observed result to the limit.
- 4
Record hardware/software versions, load, clock method, and instrument resolution; five trials do not prove all future conditions pass.
Report: 5/5 trials passed under the documented setup; mean 111 ms, observed range 108–115 ms, worst observed margin 35 ms.
Sanity checkThe mean lies within the observed range and the worst-case margin is 150 - 115 = 35 ms, not 39 ms from the mean.
Try it yourself
Independent check
Move to the bench
Create and peer-check a reproducible mini build packet for one low-voltage subsystem.
- Completed sensor, LED, or restrained motor subsystem
- multimeter or timing instrument
- camera optional
- text editor
- exportable raw log
Experiment
- State one bounded requirement and inventory exact hardware, wiring, firmware revision, parameters, and tools.
- Add one design calculation, one interface table, and a procedure another person could follow without oral context.
- Run at least three trials and keep raw observations; label expected values separately from actual measurements.
- Introduce a deliberate documentation fault by removing one critical unit or pin reference; ask a reader to identify the ambiguity, then repair it.
- Export or print the packet and inspect links, diagrams, code wrapping, secret removal, and whether unknowns remain visible.
Observe
- Expected: a reader can identify the exact setup, repeat the procedure, and tell calculations from measurements.
- Record actual reader questions and reproduction differences as evidence about documentation quality.
- Expected fault signature: removing a unit or pin makes at least one step admit multiple interpretations; the reader’s actual response may reveal additional gaps.
Prepare a one-page comparison showing how a fan, vacuum blower, printer carriage, screen, toy car, or camera inspired the bench subsystem while clearly listing capabilities not reproduced.
- Remove API keys, Wi-Fi credentials, personal paths, and location data before sharing; document appliances from external observation or manufacturer information, never energized disassembly.
Keep evidence
Bench note
Record what you expected, what you actually measured or observed, and one difference worth investigating. This is self-reported evidence, not a certification.