Firmware is often the least-documented part of a hardware product. Schematics go into KiCad. CAD goes into SolidWorks. But firmware lives in a repo that only the original developer fully understands — until they leave.
At that point, the cost of the gap becomes apparent. New engineers spend weeks re-discovering decisions. Bugs take three times as long to fix. Features that should be simple to add require architectural surgery.
This checklist covers everything a firmware handover package should include — and why each item matters.
Repository structure and build reproducibility
The repo should be clean enough to clone and build on a fresh machine in under 30 minutes.
Checklist: - All dependencies pinned to specific versions (no "latest") - Build instructions documented in the README - Toolchain version specified (e.g., arm-none-eabi-gcc 12.2.1) - Platform/target defined (MCU part number, eval board if applicable) - All secrets in environment variables, not committed to repo - .gitignore covering build artefacts
Architecture documentation
A block diagram is worth more than 1,000 lines of comments. Before handover, create:
- 1System block diagram — showing MCU, peripherals, comms buses, and power domains
- 2Software layer diagram — HAL, drivers, middleware, application
- 3State machine diagram — for any non-trivial operating mode logic
- 4Task/interrupt table — for RTOS-based designs: every task, its priority, and its responsibilities
These do not need to be polished. A Mermaid diagram committed to the repo is infinitely better than nothing.
A common failure mode: the original developer knows every peripheral register by heart and never documents the initialisation sequence. The next developer spends 3 days re-discovering a 4-line SPI initialisation quirk.
Known issues log
Every firmware package has known issues. Documenting them before handover is an act of professionalism — not an admission of failure.
For each known issue, document: - Description of the behaviour - Conditions under which it occurs - Current workaround (if one exists) - Root cause (if known) - Priority assessment
This prevents the new engineer from spending days re-discovering a known issue and either building the same workaround — or worse, accidentally removing the existing one.
Peripheral driver documentation
Each peripheral in the design should have a brief driver doc covering: - What the peripheral does in the context of this product - Initialisation sequence and timing requirements - Key register settings and why they were chosen - Error handling approach - Any vendor errata that affected the implementation
One paragraph per driver is often enough. Save the detail for the tricky parts.
Test harness and validation procedure
A firmware handover without a validation procedure is incomplete. Even for a V1 prototype, document:
- How to flash the firmware (tool, command, target)
- How to open a debug console
- What to observe on a successful boot
- How to exercise each core function manually
- Any automated test scripts included in the repo