Documenting and releasing your own robot

So far you have been a guest in other people's projects. Now flip the roles: you have built a robot, and you want someone else to be able to build it, or at least understand it, without messaging you. The honest test of documentation is whether a competent stranger, with only your repository, can reproduce your result. Most hobby hardware fails this test, not because the design is bad but because the knowledge lives in the builder's head. This lesson turns that knowledge into files.

Why documentation is the real product

A robot that only you can rebuild is a one-off. A robot with a good repository is a project: others can fix its mistakes, adapt it, and send you improvements. Documentation also helps your future self, who will not remember why a resistor is 4.7 kilohms or which servo was swapped in the second prototype.

It also means that the habits you learned as a contributor now work in your favour. A clear README, an issue template, a CONTRIBUTING file and a licence are exactly what you wished other projects had when you arrived.

Structure your repository

A layout that keeps hardware, firmware and documents apart is easy to navigate:

my-robot/
  README.md
  LICENSE-firmware
  LICENSE-hardware
  LICENSE-docs
  CHANGELOG.md
  hardware/
    schematic/      (KiCad project or exported PDF)
    pcb/            (layout and manufacturing outputs)
    cad/            (FreeCAD or other source, plus STL files)
    bom.csv
  firmware/
  docs/
    images/

Commit source files, not only exports. A PDF of a schematic cannot be edited; the project file can. Exports such as Gerbers and STLs are useful for builders, but they can also be generated again, so they often belong in the release assets rather than the main tree.

A README that works

Write the README for the person who has never heard of your robot. A reliable skeleton:

# Name of the robot

One sentence on what it is and does.

![Photo of the finished robot](docs/images/robot.jpg)

## Status
Prototype, tested on a bench. Known issues listed below.

## What you need
- Bill of materials: hardware/bom.csv
- Tools: soldering iron, hex keys, 3D printer (optional)

## Build
1. Order the PCB using the files in the latest release.
2. Solder following docs/assembly.md.
3. Flash the firmware (see firmware/README.md).

## Wiring
See the diagram in docs/images/wiring.png.

## Safety
Battery warnings, motor current limits, anything that can hurt someone.

## Licences
Firmware, hardware and docs are licensed separately, see the LICENSE files.

## Contributing
Issues and pull requests welcome. See CONTRIBUTING.md.

Put the photo and the one-sentence description first. Visitors decide within seconds whether to keep reading. List known problems honestly; builders trust a project that admits its flaws.

The bill of materials

A BOM lists every part needed. The goal is that someone can order everything from it without opening your schematic. Keep it as a CSV so tools can read it.

Name exact models where compatibility matters, and say why where it does not ("any board with..."). Include the quantities and the notes: the notes are where hard-won knowledge about substitutions goes. Parts get discontinued, so record the manufacturer part number alongside a supplier link rather than only a link.

The wiring diagram

Wiring is the part most often missing and the most painful to reverse-engineer. Provide at least:

• a schematic exported from your design tool, or a clear hand-drawn or Fritzing style connection diagram for simple builds,
• a pin table mapping each firmware constant to a board pin and the thing it connects to,
• the power path: battery, switch, regulator, motors, and where grounds join.

A pin table is cheap and removes whole classes of questions. Draw power wiring distinctly, as most expensive mistakes (reversed polarity, a motor on the logic rail) happen there.

Photos

Take photos while building, not afterwards. Useful ones: the finished robot from two angles, the electronics layout with the lid off, close-ups of any tricky solder joints or connectors with orientation, and any jig you used. Use a plain background and good light, compress the images, and add short alt text. Photos reduce the volume of questions more than any paragraph.

Licensing your robot

You met licences in lesson 1. A robot repository usually needs three, one per kind of content:

Pick deliberately. If you want your design to remain open when others modify it, choose a reciprocal option. If you want maximum adoption, choose permissive. Check the licence texts, and any guidance published by their authors, before committing, and add the licence files at the repository root. A repository with no licence is not open: others have no right to use it.

A release checklist

A release is a named, tested snapshot that builders can rely on. A short checklist keeps you honest:

• Build the hardware or firmware from a clean checkout, following only your own README.
• Run whatever tests you have, and a real power-up on the robot.
• Update the BOM, pin table and wiring diagram to match what you actually built.
• Review the README for steps that changed.
• Update CHANGELOG.md: what is new, fixed and changed.
• Export manufacturing files (Gerbers, drill files, STLs) and check them in a viewer.
• Choose the version number (below), then tag, push and publish.

Tags, releases and semantic versioning

A Git tag is a permanent name for one commit. A GitHub release is a tag plus a description and attached files, such as a firmware binary, a zip of Gerbers, and a BOM.

git tag -a v1.0.0 -m "First public release"
git push origin v1.0.0

Then create the release from that tag on the hosting site and attach the assets. Semantic versioning uses three numbers, MAJOR.MINOR.PATCH, with a clear promise to users:

• MAJOR changes when something becomes incompatible: new mounting holes, a changed connector pinout, a firmware protocol change.
• MINOR adds something in a way that keeps existing builds working: a new optional sensor header, a new firmware feature.
• PATCH fixes a mistake without changing how things fit or behave: a corrected silkscreen label, a bug fix.

Hardware people sometimes also use revision letters such as Rev A and Rev B for boards. Either approach works, but pick one, write it on the board and in the repository, and keep them consistent. Never edit a published tag; if you find a mistake, publish a new version.