Documenting a scientific hardware project is hard. If you write it after the fact it is often incomplete. If you write it during building it is normally a mess. Either way your bill of materials tends to get out of date. There have been attempts such as DocuBricks to automate the building of bills of materials, but they are hard to update, and they limit your freedom in documentation style. Many projects simply use markdown as it is a minimalistic and easy to update.

The Bath Open INstrumentation Group have spent a lot of time discussing what we want in a documentation system. We came to the conclusion we wanted the format to be simple enough to be written in a text editor and saved into our git repository, but we also wanted it to do things like build the bill of materials automatically. The general ethos is: “humans are good at writing documents, computers are good at counting”.

We are currently developing GitBuilding, which is an implementation of a standard which is evolving alongside it. The standard is essentially markdown with extra meta data, but components can also be defined in YAML files. This files are simple to edit in a text editor and can be tracked in your git repository.

There is an example project using GitBuilding.