Online / 5 & 6 February 2022


GitBuilding: Open source documentation for open source hardware

GitBuilding is an Open source program for writing hardware documentation. GitBuilding uses your tags and meta-data to automatically generate and insert bills of materials into your documentation. It correctly links different steps to one another (even when you have multiple variants), allowing you to write instructions once and reuse them for multiple projects. It also shows previews of 3D files and lets you easily include links to generated zips and other files in the correct places. You can output the entire documentation in pure Markdown, HTML, or PDF.

Open hardware is beginning to mature. International agencies such as the European Commission and UNESCO see open hardware as key to open access, especially for science hardware. Open hardware could help bring an end to the reproducibility crisis where researchers cannot replicate the work of others. However, open hardware has a key hurdle to overcome: documentation.

Documentation is important for any open project. You can't study and improve something unless it is documented. For hardware the problem is more pronounced, distribution of hardware relies either on people replicating a design themselves, or on a manufacturer producing the design. Without assembly instructions a project can't be used by anyone, for anything but the most simple project, the digital design files are not enough.

As open hardware matures documentation becomes even more important. Most people don't have the time to build all of the products they use. Even those who care about open hardware want to buy a pre-made product. To manufacture a product the documentation must be far more complete, including enough design rationale that a manufacturer can fix problems, and containing not just assembly steps, but also quality assurance procedures.

GitBuilding is a tool designed to allow open hardware designers to keep markdown documentation with their hardware designs, such as in a Git repository. Extra syntax has been introduced to semantically link pages together, and to identify when tools and components are used. This allows the automatic creation of Bills of Materials, as well as reuse of specific instructions for multiple variations of the same project.

GitBuilding was initially designed for the OpenFlexure Microscope (OFM) project. The OFM is an open source laboratory grade motorised microscope that is being trialled for malaria diagnosis in Tanzania. The open project plans to support manufacturers across the world in selling the OFM as an in vitro diagnostic (IVD) device. For this to be possible our documentation must be complete enough that manufacturers can verify the microscopes performance and design, and their own manufacturing of it to a standard acceptable to their IVD regulator. GitBuilding must be powerful enough to support this documentation.

GitBuilding is now needs to generalise. The project needs to be sure it is collecting the correct data for other types of hardware and for other industries. We need to gather input from across the open hardware community, so we know what data needs to be captured, and so where possible this information can be captured exactly one, and used wherever it is needed.


Julian Stirling