DocuBricks: Documentation Tool for Open Plant Technologies
This project has successfully built an open source hardware documentation software and an online repository called DocuBricks (www.DocuBricks.com). The software tool is (according to user feedback) easy to use and helpful in a wide range of hardware projects. It saves documentations in a modular and accessible XML format. The database is citable and the first biology related documentations have been uploaded – many more are to follow from OpenPlant Fund projects and the Open Science Hardware Movement.
The Idea
Common biology related hardware tools often benefit from modifications for application to specific plant science experiments. Open source hardware tools can be a potential solution because they are modifiable and low cost, enabling low numbers of produced parts. In practise, however, replicating, sharing and quality assessing open source hardware projects usually turns out to require a lot more involvement than expected, because of a lack of documentation standards that are easy to evaluate and check for completeness. We have partnered with the IRNAS institute in order to implement a digital documentation tool, that will make documenting much easier and instructions more useful. We propose this tool as a documentation standard for OpenPlant funded projects and are invested to further improve the tool with the feedback of this user group after the completion of this project. The documentation tool is planned as a stand-alone, open source and free software that outputs the documentation of each project including media files as XML documents. These Documents together with a ZIP folder of CAD-files are an easily accessible way of providing all project data. We propose to add further value via a free online tool that allows e.g. the rendering of CAD files, time stamping and providing a citable link, reusing and referencing modules as well as commenting and extending on projects.
The Team
Mr Tobias Wenzel,
Graduate Student, Department of Physics and Department of Biochemistry, University of Cambridge
Dr Johan Henricksson,
Postdoctoral Researcher, EMBL–EBI, Cambridge
Dr Carlos Lugo,
Postdoctoral Researcher, The Sainsbury Laboratory, Norwich
Dr Luka Mustafa,
Shuttleworth Foundation Fellow, IRNAS, Slovenia
Project Outputs
Project Report
Summary of the project's achievements and future plans
Project Proposal
Original proposal and application
DocuBricks website
Share your research tools, cite and track impact, create hardware and improve existing projects through the DocuBricks website
On the open hardware documentation tool DocuBricks
Summary
We have successfully built an open source hardware documentation software and an online repository called DocuBricks (DocuBricks.com). We arrived at a software tool that is (according to feedback of users) easy to use and helpful in a wide range of hardware projects and saves documentations in a modular and accessible XML format. The database is citable and the first biology related documentations have been uploaded – many more are to follow from Open Plant Fund projects and the Open Science Hardware Movement. We will continue to develop DocuBricks to serve as a high quality repository for Open Science Hardware.
Report and Outcomes
We started off with the observation that open source hardware, especially in a biological and plant science context, is currently held back by hurdles of sharing hardware documentations – such as effort required to document a project, lack of quality guidance and control as well as expectation management. Documentations are the key information set to make hardware open source and reproducible. Within the scope of this grant, we build an extensive documentation tool DocuBricks to address many of the observed deficits. Here is a list of specific achievement in accordance to our original proposal and extending beyond it. All projects and download links can be found directly on DocuBricks.com:
A open source software DocuBricks editor (desktop software in Java), that provides users with a framework to quickly document a project in a modular fashion with step-by-step assembly instructions for each module (called “Brick”), while dropping in images and other media files to support easy understanding by readers. The editor then saves the project in an accessible XML format together with a folder containing all design and media files.
The authors of the documentation are guided by the editor software to structure and explain the project along its functionality (earlier referred to as “logical parts”) and then indicate its implementation (earlier “physical parts”). This is a major difference to all other attempts known to us and significantly enhances the ability of later readers to understand design decisions and help evolving the project – this is continuously referred to as the key advantage of open source hardware.
Modularity enables coexistence of incompatible licenses: Many licenses (such as the CERN license or CC-BY-SA) used for open source hardware are "share-alike" - meaning that the person modifying the project has to re-publish it under the same license. This creates problems when a project should be created and published, that builds on two existing projects with different licenses. We solved another major problem here: One can give different licenses to the modular bricks of a project documented in DocuBricks (default: top brick license applies to all bricks lower in the bricks hierarchy).
We have built an open source offline viewer (XML style sheet + java script and HTML), that displays the projects (XMLs + files) created with the DocuBricks editor interactively in a browser. The authors need not worry about style and layout when using our tools. The viewer is stand-alone and works without internet access – just right click on the XML file (must be in the same folder as the viewer software) and select: open with – Firefox browser. We have stopped developing the offline viewer recently in favor of an online viewer directly hosted on the website (see section on deviations from proposed grant plans).
We have tested the tools on several examples, as have some project partners and we have iterated the software tools to be meet the practical needs and to be easier to use and understand. One example of added features is the option to include instructions with parts in the Bill of Materials (BOM). This provides an intuitive location to add e.g. post processing steps for 3D printed parts such as drilling into printed holes. Depending on where the parts are sourced, this might not be necessary to perform and thus would unnecessarily take up space in the assembly instructions of the main documentation.
We have developed an online repository where projects documented with the DocuBricks editor can be uploaded and shared (and soon be displayed online - on the new website we are writing). As proposed, this website is citable via digital object identifiers (DOIs). These are permanent, internationally curated links and the standard for referencing in the academic community. We believe a functional online repository based on a functional documentation format like ours is of great value to the community, because it allows users of hardware documentations to evaluate and extend on hardware in a much more meaningful way. This is both essential for successful open hardware development and for appropriate recognition of impact and re-use for contributors from the scientific community.
We have also participated in a number of workshops and meetings, where we have pushed best practice guides, accessibility to hardware publications and tools, standards for the fields and information of the public. See our (new website soon) for major references to media reports.
Deviations from proposed grant plans
Generally, user interactions and iterations of our software have confirmed our initial hypotheses on what tools are needed. The major exception is perhaps the evaluation of “stand alone” of our software tools. In order to make the software as open source and accessible as possible, we created the software as offline-desktop software, which can for example, can be version controlled and shared on GitHub. We learned that most users want interactive online tools instead and that most don’t worry about the fact that this makes the software in itself less distributable and that we have to make sacrifices on version-controllability. Online tools require a different backend design and programming language, so this is a major re-direction for us.
We were also proposing possible additions to the project, most notably an app and possible integrated rendering tools for CAD files. We have decided to not yet attempt these, as refining the documentation tool through iterations and guidance of initial users seems more essential. Instead, we are now integrating the Altmetrics tool, to provide journals with feedback on user interactions with design files and the documentation, to improve academic impact reports for Open Science Hardware. Hardware innovation in science is currently typically undervalued, which keeps many scientists from engaging in it.
I, Tobias Wenzel, want to thank the most amazing DocuBricks team, especially Johan Henriksson, for the exceptional work and commitment to the project. Thanks to the motivation and idealism to help the Open Science Hardware community as well as great teamwork, we have managed to create a very useful tool that is un-matched so far. I am confident that we invested our hundreds of hours of voluntary time, thought and discussion well into this open project.
Follow-On Plans
We want to engage in further publication, communication and outreach for the tool, to make it more widely known and used.