Hardware documentation Guide

A guide to open source hardware projects documentation

Background

After analyzing open source hardware documentation and existing templates, we are convinced that (1) documentation should grow with the different phases of a project and (2) the documentation should not restrict itself to the technical documentation necessary to reproduce the hardware, but should have a larger scope: the goal is not only to make the hardware (re-)producible, but to facilitate collaborative work in the development of the hardware (see Fig below).

Hardware project documentation is diverse, it grows with project development (depicted by orange boxes from left to right: ideation, specification, concept development, prototyping), and go beyond the technical documentation (black box)

Accordingly, we created both a template for hardware project and this guide. We hope to facilitate the creation of hardware project documentation with these two tools.

Guide organisation

The guide starts with a description of the steps, with a checklist of information to add at each step. This corresponds to the elements of the template in its “incremental template” form. In the checklist, each element is linked to the corresponding sub-chapters of the guide that explain what that element is.

The book chapters and subchapters follows the order of the “full template”, which correspond to all elements one may include in an advanced project: readme file,community folder, project history folder, conceptualisation and specification folder, hardware design folder, and user guides folder). Some elements of the guide are not in the template, because the elements should best be organised via a different repository and linked in the readme (software, data, educational resources)

Because we expect most project to see this template when already having a prototype, we added a special chapter on starting documentation at this stage (Document when you already have a prototype).

Navigating the book

On the web version, a first table of content of chapters is found on the left bar. Once a chapter is chosen, a table of content of that chapter is available on the right bar. One can also search for specific terms.

Technicality

This is a quarto book, each element has its own quarto/markdown file and a specific code merge them together to create chapters. See the Git repository to modify this book.

Online version of the book:

URL: https://open-make.github.io/RHardware-minimaltemplate/

Guide version: 1.0

This is the first version of the guide, based mostly on the theoretical framework developed inside the Open.Make project by the authors. It was not yet tested and any feedback is very welcome !

FAQ

1. How iterative is the process ?

   • At each step, the whole content may be modified. Especially, the analysis of “Similar projects” coming in step 3, and the prototyping (step 4) are often giving new ideas and refining use cases. The vision may change when new team members enter the project, independently of the development stage.

2. What is the minimal documentation? My project is tiny.

   • The size of the project is not really affecting the number of elements that are important, it will affect the size of each element, though.
   • While you may tend to skip the community aspects of the documentation, we think these are important aspects of the development process, unless you really want to do it alone.

3. Why is the technical documentation description so small?

   • Technical documentation will be very different depending on the hardware created, we only gave general hints in this guide. As a rule of thumb, developing a hardware collaboratively with at least one other human will help you define how to organise the technical documentation.

4. When should I start documenting?

   • As soon as possible. This template allows you to start documenting your project at the ideation phase. While it might seem too early, it is useful when you want to present your ideas to collect feedback or even find collaborators. This allows to make clearer what are the important aspects of your idea, and can start interesting discussions.