IEEE.org     |     IEEE Xplore Digital Library     |     IEEE Standards     |     IEEE Spectrum     |     More Sites

Commit 71ae4482 authored by Tobias Wenzel's avatar Tobias Wenzel
Browse files

Update README.md with DocuBricks content

parent 8b04220d
# DocuBricks standard
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.
\ No newline at end of file
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.
### 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)
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)
Custom instructions (such as calibration, testing, safety, user guide, teaching, etc.)
A part is a resource listed in the bill of materials (BOM), which is needed to assemble or run the project, mainly hardware parts e.g. a screw, digital design files representing a single object e.g. an STL file for 3d printing, specialist tools, or operating software. Each part is defined in the BOM and can contain supplier information, media and their own manufacturing instructions e.g. when the object is made from a digital file or needs simple pre-processing before it is assembled with other parts.
**Modifiable design files** are a key element of open sourcing a hardware project, and are added as media files to DocuBricks documentations. The location for design files can be chosen flexibly depending on the level of integration of the design. They are either saved in the respective part, the respective brick, or even in a dedicated design brick, which details aspects of integration and customisation.
### Definitions
The following reader-friendly lists define the elements of the DocuBricks XML format:
#### <**docubricks**> tag for the start of DocuBricks documentation of the project; the brackets are not written in the following definitions
**author** id(string):
**name** (string)
**email** (string)
**orcid** (string)
**affiliation** (string)
#### **part** id(string):
**name** (string)
**description** (string)
**supplier** (string)
**supplier_part_num** (string)
**manufacturer_part_num** (string)
**url** (string) link to an internet source of the part
**material_amount** (string)
**material_unit** (string)
**media: file(s)** (url) images, videos, CAD files, and more
**manufacturing_instruction: step(s)**: step by step instructions
**description** (string)
**media: file(s)** (url)
#### **brick** id(string):
**name** (string)
**abstract** (string)
**long_description** (string)
**notes** (string)
**media: file** (url)
**license** (string)
**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
**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
**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
#### </ **docubricks** >
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment