Hi all.
There are some big changes in the pipeline for GitBuilding which will allow the documentation of more modular hardware. The features will be a bit rough an ready in the first instance, but it should pave the way to simplifying the documentation of projects like UC2 (@beniroquai !)
Current way of documenting
The problem with how GitBuilding used to work was that you first define a number of steps that need to be done, such as:
- print microscope parts
- assemble optics
- assemble main body
- final assembly and wiring.
Then for each of these you write a page of documentation. This means that if you have two variations on a microscope with different optics, you can reuse pages that are in common without repeating yourself. There was a bit of templating control to allow the images to be different.
This is what we have done for the OpenFlexure Microscope Documentation and it works pretty well.
Problems with the current system
The person documenting needs to handle things like. Which parts to print (there is some logic to warn if you use things that have not yet been made. But it is all a bit manual. This means when doing a modular project you need to yourself work out what parts to print and put them into the documentation. If you have loads of configurations, the overhead is huge.
Even worse if you use need to assemble a component a certain number of times, you need to make a new version of the page that explains how to make the component, but this time explaining how to make a specific number.
New way forward
GitBuilding already defines steps to follow or parts to use with different tagged links. We are adding a new type of link called the make link. This can then be used to define a more top down structure.
The final assembly says you need to assemble five components. The links to the instructions say these 5 components are tagged so that they need made first. These components will also use similar links to say that their parts need to be printed. It is possible to make multiple the components on a certain page.
GitBuilding will automatically count up the multiplied bills of materials, will order all of your pages so that the person reading the documentation is still shown the pages in the correct order. . i.e. print everything, then assemble the components, then do the final assembly.
For example here is a test for the Nimble mesh network, showing all the 3D printed components in a table. This informations is pulled through from other pages using the printed parts:
But from a documentation writing perceptive, to document a new configuration only a new final assembly page needs to be written.
Acknowledgments and what next
This work is part of a project on automated documentation funded by NLNet. With @drayde @eric and @jmwright. There are more cool things in the pipeline.
I need to write a bunch more documentation to make sure that it is clear how to use these features.
If anyone is working on modular hardware and wants to talk documentation. Then give me a shout!
