Sean “xobs” Cross has an excellent discussion from linux.conf.au on documenting Open Hardware modules (undocumented hardware is bad).

We all know documentation is important, but often times it’s seen as either something to be done before a project starts — in which case it’s often outdated — or after the project is complete — at which point it’s easily forgotten. This problem is especially difficult with hardware projects, which can be extremely obscure and dense.

Professional chips generally come with a reference manual that describes the hardware. This manual is usually created by a dedicated staff that uses publishing tools and spreadsheets to create a final PDF file. As small open source developers we rarely have the resources to create these reference manuals by hand.

This talk covers `lxsocdoc`, and covers how they document the various peripherals inside projects such as Fomu and Betrusted, and provide motivation for treating documentation like code. They show why documenting as you go is both beneficial to end users, as well as beneficial to yourself, and why an approach such as the one taken in `lxsocdoc` can help yourself today, not to mention your future self.

See the video here.