Docubricks Review

During this MakerNet phase two, one of the areas we’ve been exploring is a collaborative platform(s) for sharing (and finding) designs of useful items, enabling people anywhere to make them. This includes sharing digital design files, instructions, and all the other information that might be needed to reproduce an item, as well as the ability to adapt and improve designs (version control), and for some authorized groups to tag or certify certain items (for instance, that they meet specific requirements or standards, which is important for safety). We have referred to this concept as “Makepedia”.

In this exploration, we identified Docubricks as a tool that may provide a useful way to document hardware designs’ instructions and related information. Docubricks founders, Tobias Wenzel and Johan Henriksson at the University of Cambridge, and a number of contributors, developed the software with this mission in mind: “to provide infrastructure for a sustainable development of Open Science Hardware.” The problem they are working hard to solve is lack of sufficient digital tools for sharing useful open science hardware projects that integrate different types of components and for validating measurement quality via calibration of equipment made in different locations. This is a problem we had identified in the sharing of our own digital designs, especially for hardware projects that have assemblies and/or require more robust documentation for build and use by others and need some level of reliability. Docubricks is approaching this problem by providing a digital standard and format for documenting hardware projects. We have tested their tool these past several months by setting up and publicly sharing one of Field Ready’s complex projects – the Lifting Airbag.

In this review, I’ll be focusing on my experience, as a non-developer, in setting up and using their software from October – December 2017. We had identified criteria earlier for digital knowledge-sharing, outlined below. We did not expect all criteria to be met by Docubricks, as those criteria were not their own; however, on those that did overlap, I provide comments.

Ease of Use

Set Up

Set up currently requires use of their offline editor (below). Docubricks provides basic instructions on their site which I followed with mixed success. Some initial challenges I faced were: saved edits in the editor didn’t actually populate the web page, the project properties page on the web initially was too large for my laptop screen – couldn’t scroll or see the bottom buttons, authors section wouldn’t update, error message when attempting to download the project from the web, and others. Some of these were user error, some were bugs.

Tobey, and later Johan, were responsive to issues and bugs identified during the set-up process and made the required effort to ensure a presentable and working digital Lifting Airbag project. We had planned for a set-up time of two weeks part-time to upload all projects, including this one. The entire process took about four weeks and some late nights by all. Notably, during this process, Tobey clarified that the software is meant for high-quality developer-targeted hardware documentations that allow other hardware developers to understand and modify the designs. i.e not novices!

In regards to setting up projects via the mobile phone, it is not built for this. Viewable, yes; editing, no. The offline editor works best with a large screen as there are a lot of rows, boxes and details to organize within the editor. Also, I don’t believe there is a mobile app version of the editor.

Viewing

We have yet to receive external feedback on the digital Lifting Airbag instructions (to do this, see here); however, one of the main designers of the hardware was pleased (Usamah: “fantastic” and “looks professional”). From my perspective, it seems relatively easy to use from the viewer’s perspective: one place for all documentation related to the project, a linked index to jump to the desired section, assembly pictures matched to instructions, a standard format from project to project, to name a few helpful features. We had also desired the ability of viewers to download a PDF or offline copy as often times, where humanitarian practitioners often work, internet access may be unreliable. Docubricks is developing this option but it is not yet available. A simple option at this time is doing a Ctrl+P and manually creating a PDF from the web version. Considering that Docubricks is not intended as a platform, functions such as project searchability are excluded from this review.

Licensing

Docubricks enables declaration of the owner’s chosen license on each brick as needed.

Access

It is open and free to anyone. No user ID is required to access the different projects shown on their site. If the projects are linked or hosted on different sites, access will be determined by that site.

A viewer is able to download the project as an XML file, or, using Ctrl+P, print a PDF which will mimic the online presentation. In editing mode, the offline editor, of course, is usable without internet access. However, once the content has been inputted, internet or intranet access is necessary to populate and be visible.

Content Iteration

This is possible by the project owners or viewers. However, it is on the side of the project owner to track (and show, if desired) iterations. For example, I can “save as” the Lifting Airbag project as a new file and edit accordingly. If I give it a name like “Lifting Airbag v2”, this would indicate a new version building from the prior. A viewer, as mentioned above, can download the project as an XML file then open it in their Docubricks editor, making the desired changes.

Findability

Here I want to note that this is not a current goal of Docubricks. The software they’ve developed can be linked to or hosted on any site. It is not a platform in itself, though a person can go to its website and see a list of projects. In terms of our needs, this flexibility and mobility is helpful. People within our HM network tend to use a variety of platforms for file sharing and knowledge sharing, and like a belt holds up any pair of pants, I see Docubricks as a tool that may supplement “any” such platform. At least in the future.

Completeness

On a project development timeline, Docubricks has made significant progress but not ready for prime time. As an open source initiative, they’ve made tremendous progress and have, I think, a clear value-add to the open hardware and science community. More financial and human investment are necessary to get this to the level Tobey and the team have shared: to become the gold standard for hardware related academic documentation, collaboration, publishing and teaching; as well as to get this to a level I’d feel comfortable recommending it to our teams as our go-to documentation tool.

Overall

The Docubricks team are rock stars with a great open source software tool that has yet to be fully realized. They need additional investment to build further and create the solution that solves a real problem within the open science hardware community. In addition, features for DocuBricks can be requested directly via "Issues" in their GitHub repository, where they make their code available: https://github.com/DocuBricks for others to contribute to.

What does this mean for “Makepedia”?

It gives us insight into desirable content structure for sharing designs and information. Docubricks uses a modular structure in which hardware parts can be broken into “bricks” and “sub-bricks”. It also enables linking to all files, media and details in one place. Below, the content structure is shown on the left (way left, offline editor; next, web viewer).

How the structure within the offline editor relates to, or creates, the structure seen in the web page was not intuitively apparent to me. It took a few go-arounds, pushes to the web, and conversations with Tobey to understand how to create the “ideal” structure. The main brick is an intro to the Lifting Airbag System and the important information to understand before building it. Then it “breaks down” into sub-bricks that continue with important information, then instructions (tools and assembly) about the specific components of the System. This is followed by test and usage documentation. Parts, BOM and Authors are treated as separate sections and are not “bricks”. The BOM must be entered piece/part one by one and field by field, similar to database inputting. A preference would be to have the ability to upload CSV or XLS files to save time and improve accuracy. The Parts section is populated by what is entered into the BOM and will appear on the web page tied to the relevant System component (lifting airbag or valve box in this case). I see this as having pro’s and con’s. A pro is that it forces accuracy to some degree in that all parts shown will be listed on the BOM and vice versa. A con is that more flexibility may be desired in data fields available for inputting. For example, “material usage” field didn’t quite fit for our purposes. The unit options were Kg, Liters or None – so all ours were None. The below image shows the form fields for inputting one part of the Value Box.

I do wonder how more of a balance might be found between project specific flexibility and product line, or industry, standardization. We do desire more feedback on this structure from the open hardware community. To share your thoughts, please see the Lifting Airbag item here and complete the questionnaire contained in the same spreadsheet.

Thank you for reading! Questions and comments are appreciated and welcome (naiomi.lundman@fieldready.org). To explore Docubricks further, see www.docubricks.com and/or contact Tobey Wenzel (tw347@cam.ac.uk).