Some big changes in the pipline for GitBuilding

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:

  1. print microscope parts
  2. assemble optics
  3. assemble main body
  4. 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!


Hey Julian, thanks for the update. And finally, again a reminder to have a look at this powerful tool! I was wondering why this big change is specifically great for UC2? :wink:
We rely on (mostly) Autodesk Inventor generated/designed files and hence don’t really have control over their version or can build the parts on the fly like openscad. Would this still be beneficial to use the new version of gitbuilding?


Hi Bene,

This is not for the cad, but the wordy type “do this”, “do that” type documentation for end users.

With the new version you should be able to write a page of explanation for each cube. Then if you want to make docs for a specific configuration you tell it which cubes goes where and it should generate a start to finish explanation manual for the whole process with a consistent BOM.


Ah, so more “hierarchic” point of constructing an assembly made out of sub-assemblies, where each can be updated individually and versioned? Cool. Examples? :stuck_out_tongue:

An example and some better documentation are coming soon!

Great! Let me know when you’Re done. I have informed “the team” :wink:
We’ll look into it. Probably better than this

The features are still not yet properly documented, but here is some example documentation for a different project. This pull request is moving to the new syntax.

1 Like