And how to make it useful for your contributors

Minimal viable documentation for building or contributing

A common mistake of open projects is to leave documentation to the end, when “things are done”. This is understandable, as projects on their initial stages tend to change quite a bit, including the parts used, their design, how everything connects together, etc. We call it a mistake, because not having a minimal viable documentation prevents others from understanding how your project comes together and contributing to it.

Also, leaving documentation to the end leads to details and the reason behind certain decisions being missed/forgotten. Which in turn leads to more hard time replicating a project, and more time wasted revisiting ideas/implementations that did not work (and you just forgot why).

An alternative to this is to make your documentation evolve with your project. It does not have to be polished. It needs first and foremost to exist and to be continuously updated, together with everything else. A good practice is to set a time each day, by the end of a working session and make notes of what was done and why. This will allow you to have a much easier time making a polished documentation when things reach a stable state, and also for other people to see how the project is evolving, how they can contribute and why things are the way they are.

Bill of materials

The bill of materials, commonly just named “BOM” is usually in form of a table. It should contain information in a way that is makes it easy for interested people to know if they will be able to source all needed materials and if they have the necessary tools and skills to replicate your project. A good starting point contains:

  • what parts were used, with links to suppliers
  • why they were used (for instance, why is something build out of acrylic and not wood?)
  • what tools and skills are needed are needed to replicate the designs (do I need a lasercutter? Do I need to know how to use a sewing machine?)

Access to materials

When building your bill of materials, it is good to keep in mind that not everyone has access to same distributors. If you live in Europe and North America, you have easy access to everything that is listed on Amazon. However this is not true in many parts of the world. This is another reason why listing what you are using, and why you are using it, are good practices. In this way people can understand a certain decision for a part, and come up with a local resource that will do the same job.

Another good way of approaching the issue of material availability is to add more than one distributor to your Bill of Materials. Or even create an “issue/call for participation” on your project, where you ask interested people to create a “local bill of materials” where they share which components they can find from their local distributors and which they needed to find replacements for.

Bill of tools

The rationale about a bill of tools was covered in unit 4.1 Accessible Docs, and it makes sure people know what tools they will need to source to be able to replicate your project. Make sure to include it in your documentation!

Bill of skills

The rationale about a bill of skills was covered in unit 4.1 Accessible Docs, and it makes sure people know what skills they need to have to be able to replicate your project. Make sure to include it in your documentation!

Assignment: Reach a minimal viable documentation

  • Update your documentation with with:
    • Bill of materials
    • Bill of tools
    • Bill of skills


tools for making instructions/BOMs Gitbuilding Dokubricks Instructables Wikifab Appropedia Kitspace 1-click-BOM Wikifactory

next: Digital fabrication & electronics  

Help us improve content and suggest changes to this page.