Download the Editor

Our (offline) editor software helps you create a good documentation of your project that complies with the DocuBricks XML scheme (below), as required for uploads to this online repository. The editor enables you document to a project in a modular fashion along it's functionality, with all files, media and details linked into place.
Our modular documentations are well suited for open source hardware projects, enabling the communication of design decisions with advice on assembly, testing and usage. They differ from simpler linear assembly-only documentations as used in commercial home-assembly kits or repair guides, because those do not aim for the project to be modifiable by others.

Please download our free and open source (java) editor from the repository behind this link:

GET STARTED HERE: DocuBricks Editor downloads

No installation is needed for this software, but it is written in Java and you might have to update your java version for this software to work correctly. The editor will save your project into a XML document and a folder with your files (images, videos, CAD, etc.), which you can save on your PC or host for example on GitHub to re-open, modify or fork later. Once you are ready to submit the project to this repository as draft or release version, please log-in and upload the files as one zip-folder.

    Tips and tricks for the editor use:

  • Drag-and-drop media and design files to the desired location in the documentation.
  • Write "todo" into a field to highlight it for later attention.
  • Use DocuBricks to create a modular documentation by describing parts of your hardware, wetware, or code in their own "bricks". We recommend to create a general "top-level" brick that describes the general aim of the project and then referring to "sub-bricks" by naming them as part of the content-section of the top-brick or other sub-bricks.
  • Group parts in the content of a brick and give them a name that reflects their functionality. In this way, you can indicate to the users for what reason you included these set of screws, nuts, or other parts.
  • Add manufacturing instructions to parts, if producing or finishing this part to be ready for use requires attention.
  • Add custom instructions to a brick to detail important aspects of the project such as calibration instructions, testing, usage procedures, safety considerations, educational ideas, or further suggestions to improve the project.
  • Save your project to a new folder location in order to copy all associated files into a new directory.

Source code

All our software is proudly free and open source. At our GitHub repository, you can find the source code of the java editor, the type-script (java-script) and HTML viewer used by this website to render the XML-based documentations nicely, and the code for the website itself.

DocuBricks source code repository

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.

Modular projects using bricks

A documentation brick is nothing more or less than a standalone part of the documentation as freely defined by the author. One could write the entire documentation of a project into one brick, but creating dependent bricks to the “project overview brick”, helps disentangling the project to make it easier to document, understand and evolve. The following questions might help you identifying appropriate parts of your project that could be documented as a brick: What parts of the hardware could be used as a component of another project or a variation of this hardware? What solutions do you find most noteworthy given your experiences during the design iterations? What separate functions or actions does the hardware perform?

    Every brick contains the following documentation sections:

  • Brick overview (description)
  • Copyright (License and author; inherited from higher bricks if not specified)
  • Components (Functions of the brick’s hardware and their implementations. Implementations 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.

File storage

All files that are referred to in the DocuBricks XML document should be stored in an accessible folder close to the document. When the documentation is created with the DocuBricks editor software, such a folder called “usdata” is automatically created with all the files that are dragged-and-dropped into the editor. Re-saving the project to a new location via the editor will place all files in this folder, except the docubricks.xml itself.

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 >