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.

While I was at the Bath Open INstrumentation Group we 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”.

I am developing GitBuilding which is based on markdown with extra metadata. This files are simple to edit in a text editor and can be tracked in a git repository.

For an example of a project using GitBuilding see this pre release of the new OpenFlexure documentation (https://build.openflexure.org/openflexure-microscope/v7.0.0-beta1/).