DocuBricks is a modular XML-based documentation standard for Open Source Hardware projects. It is particularly suitable for multi-fabrication method and academic products and supports illustrated assembly instructions for non-experts.
## Introducing the DocuBricks XML format
The DocuBricks format is a modular documentation structure for high-quality presentation of open hardware projects. We feel that the available tools were not sufficient to enable sharing useful open source hardware projects that integrate different types of components. These projects should be documented in a modular fashion where it is easy to assess how the project solves a problem, whether the information is complete and if calibration strategies etc. are given.
We are still extending the format according to the needs of the users. In the future, we intend to develop the format into a more formal standard.
The DocuBricks format is a modular documentation structure for high-quality presentation of open hardware projects. We feel that the available tools were not sufficient to enable sharing useful open source hardware projects that integrate different types of components. These projects should be documented in a modular fashion where it is easy to assess how the project solves a problem, whether the information is complete and if calibration strategies etc. are given.
### Basic structure
A DocuBricks documentation of a hardware **project** is characterised by a hierarchy of modular documentation bricks. A brick is a standalone piece of documentation describing a functional part of the overall project and can contain more specialised bricks lower in the hierarchy.
Every brick contains the following documentation sections:
### Brick overview (description)
#### Brick overview (description)
* Copyright (License and author; inherited from higher bricks if not specified)
* Components (**Function**s of the brick’s hardware and their implementations. **Implementation**s are references to other more specialised bricks or parts from the “bill of materials”; bottom level bricks can only contain references to parts)
* Assembly instructions (stepwise instructions with associated media files)
...
...
@@ -47,8 +45,8 @@ The following reader-friendly lists define the elements of the DocuBricks XML fo
***media: file(s)** (url) images, videos, CAD files, and more
***manufacturing_instruction: step(s)**: step by step instructions
***description** (string)
***media: file(s)** (url)
***description** (string)
***media: file(s)** (url)
#### **brick** id(string):
...
...
@@ -61,17 +59,17 @@ The following reader-friendly lists define the elements of the DocuBricks XML fo
***author(s)** (**id**(string))
***function(s)** (**id**(string)):
***description** (string) name of the function
***implementation(s)** (**type**(“brick” or “part”), **quantity** (int) nr. needed pieces, **id**(string) of brick or part respectively
***description** (string) name of the function
***implementation(s)** (**type**(“brick” or “part”), **quantity** (int) nr. needed pieces, **id**(string) of brick or part respectively
***assembly_instruction: step(s)**: step by step instructions
***description** (string)
***media: file(s)** (url)
***component(s)** (**quantity**(int), **id**(string) of function) local reference to functions in the brick needed as component in this assembly step
***description** (string)
***media: file(s)** (url)
***component(s)** (**quantity**(int), **id**(string) of function) local reference to functions in the brick needed as component in this assembly step
***instruction(s) name**(string): **step(s)**: other step by step instructions of custom type e.g. safety, testing, calibration, user_manual, improvement_suggestions, etc.
***description** (string)
***media: file(s)** (url)
***component(s)** (**quantity**(int), **id**(string) of function) local reference to functions in the brick needed as component in this assembly step
***description** (string)
***media: file(s)** (url)
***component(s)** (**quantity**(int), **id**(string) of function) local reference to functions in the brick needed as component in this assembly step