Open Source Hardware Documentation Jam: A Report

Open Source Hardware documentation isn’t just about creating a set of assembly instructions that anyone can follow, so that they can build, for example, a LifeTrac tractor. It’s about accelerating innovation to solve problems more effectively and more collaboratively than at any previous time in human history.

Photo Credit: Bilal Ghalib

On April 26-28, more than forty people gathered in New York City for the first-ever Open Source Hardware Documentation Jam, an event inspired by a February meeting among co-organizers Marcin Jakubowski of Open Source Ecology, blogger and strategist Simone Cicero, and Catarina Mota of Open Materials and  OSHWA. What emerged from that conversation was the idea of an inclusive, creative conversation – the Doc Jam, sited in New York but widely promoted among the open source hardware community and beyond.

The diverse group that gathered for three days in April included software developers, hackers, storytellers/bloggers, designers, facilitators, and representatives from open source hardware companies. Their goal was to rethink how documentation can work best in an open source world. In a recent radio interview, Doc Jam co-organizer Simone Cicero described the thrust of the work: “The idea is to build some sort of interoperability standard so that we may achieve more logical consistency between different platforms … so that you can be sure that what you document is something that is actionable for a person to replicate your project.”

Over the course of the Jam, participants came to envision a standard that, when widely adopted, will enable designers and makers to easily track down open source hardware projects of interest according to key descriptors and to share their own work with others. They began to hash out what excellent documentation looks like and how it could be created efficiently.

Marcin Jakubowski, OSE’s founder, sums up the significance of the first Doc Jam this way:

It was great to see all kinds of interest from universities, companies, and individuals. Everyone there understood why documentation is important. Without documentation you just can’t build on other people’s work. Long ago, the invention of writing allowed humanity to leap forward. Imagine the potential if barriers were removed from the collective human ability to build upon every piece of knowledge. This happens only in a limited way today.

Key to implementing that vision is developing a taxonomy for open source hardware documentation. Tim Asp, who works with Dozuki, explained to the taxonomy group at the Jam as they settled down to work: “So the goal of this session is to identify key pieces of information that are required to make documentation available and understandable for the end user, how to package that up and make it accessible between services.” Tim envisions a documentation process that will be everything documentation in the past has tended not to be—easy to create, visually rich and precise, easy to find, and easy to access: “The goal is to make it easy to share online, painless so that people can really edit that information.”

Marcin, who participated in the taxonomy group and also managed to capture key take-aways from the Doc Jam on video, offers this report: “In the taxonomy group, we discussed all the elements that you need to create comprehensive documentation for a physical object. We came up with a metatag of critical elements that allows anyone to find specific information on a piece of hardware.” As it turns out, the oManual file format being developed by the team behind iFixit and Dozuki emerged as the best starting point. iFixit/Dozuki is getting oManual approved by IEEE as a recognized standard for open manuals, and Marcin sees that it could be utilized by OSE: “We just found out about it, and that’s great because if Dozuki is already developing a recognized, open standard, that fits with our open source process. The oManual standard allows a taxonomy to be imposed upon our documentation materials. The advantage of an open standard is that the documentation can then be parsed and displayed in any way that is desirable. Thus, there is a separation between content and the display of that content – which makes the oManual file a robust and flexible was to store, organize, and display open hardware documentation.”

oManual

Using a stack of Post-It notes, the taxonomy group delineated essential metatags and metadescriptors to be incorporated into  documentation and organized them on the wall:

• OSHW – The tags that identifies the entire project as open source hardware
• Entity – The person or organization responsible for the project
• Project Name – Something unique that identifies the specific project
• Version – An alpha-numeric code that increments at milestones
• Completion Status – The general maturity level of the project
• Version Date – Last time the version number changed
• Terms of Use – Any terms of use or licensing compatible with the latest version of the open source hardware definition
• Summary – The project pitch – short (140 characters?)
• Keywords – A comma separated list of synonyms – tags for search engine optimization
• Description – The detailed description of the project
• Predecessors – This project descended from…
• Content Location – A URL to the main project repository

Beyond these, group members also targeted other metadescriptors that would be helpful for turning up the right project:

• Difficulty Level
• Author / Contributors
• Required Tools
• Approximate Cost
• Required Space

The biggest little Post-It ever turned out to be the simple tag “OSHW” (for Open Source Hardware). Marcin explains:

We took a picture of that little Post-It, and we said, “This is the result of the entire jam!” That is to say – if only any open source hardware project identified itself as such – that would make life much easier for others to respect the open status and and therefore be more inclined to work with it. This may not sound like a big deal – but many times, people miss out on great collaboration opportunities when searching the internet because it appears that a project is not open – or  they waste a lot of time pursuing collaboration with a certain project that appears to be open, but turns out to be very protective. Establishing a clear identity for Open Source Hardware has the potential to go a long way in terms of accelerating the progress of the open source hardware movement – while creating clear expectations of what it means to be open.

Metatag: OSHW (Open Source Hardware)

The power of that tag should not be underestimated because it will enable people to find open source projects relevant to their needs through searches. As open source projects proliferate, being able to find the ones you need will be key. At this time, finding the work that has already been done can be challenging. It’s in many different places, captured in many different formats that aren’t systematically indexed anywhere or readily searchable.

Coming up with an optimal taxonomy is, however, only the beginning, as Marcin points out:

The next step will be to get people to adopt it and spread that so people actually start tagging things, but I think our first step is to say, “OK there’s a bunch of people who got around a table to discuss what open source documentation is and we came up with this file format and this tag so that anybody can find an open project simply via the tags.” If someone has the culture of open source economic development, it will make their life much easier in terms of developing meaningful collaborations.

Just as making open source hardware documentation searchable and accessible is key, no less important is making it easy to produce and easy to understand. Traditionally, creating documentation has been a laborious process – add-on work nobody gets excited about doing. And anyone who has ever sat down to decipher a printed sheet of assembly instructions illustrated with black and white diagrams knows how frustrating sub-optimal instructions can be.

With all that in mind, the iFixit team, widely known for their excellent instructionals, created Dozuki, an online documentation creation solution that makes it easy to create excellent, full-featured  documentation, even in tandem with the production process. Designed for computers, iPads, iPhones, and Android phones, Dozuki enables documentation creators to easily create and incorporate full-color images, videos, voice annotations, text instructions and links into instructional apps. Dozuki instructionals are stored online for anywhere, anytime access but can also be downloaded. They are easy to update, standard in format, and searchable. Dozuki  facilitates documentation creation in real time as a procedure is being carried out – and that’s a phenomenal step forward.

Rob Kirk, OSE’s documentation manager, is exploring how Dozuki and other tools can be used to create documentation for the Global Village Construction Set’s machines. The documentation process, Dozuki-enabled,   will take now place in conjunction with a build, Rob explains:

We’re very excited to be working with Dozuki to create that organized and painless method of capturing new documentation … without slowing down the building process. We are now testing their new smartphone app that allows for instant upload, organization and voice annotation of photographs shot during fabrication and assembly. We are also working with a new video platform called Latakoo that provides a high speed upload, logging and download mechanism for high resolution footage, so remote editors can be working concurrently with the building of the GVCS machines. With these methods, accurate, accessible and visually interesting documentation will ready shortly after the builds are completed.

Also, over the years OSE has compiled thousands of Wiki pages, filled with valuable documentation. But the material is difficult to access and apply. I believe Dozuki can also be a great tool for organizing this pre-existing content and making it a more useful resource.

The picture, then, comes clear: To revolutionize how documentation can be created (and how readily) is to revolutionize the kind of documentation that can be and the kind of work it can accomplish in the world as people put it to use.

At the Doc Jam, one discussion especially pertinent to OSE focused on using Dozuki to design documentation for modularity, the approach OSE is taking to the design of the machines in the Global Village Construction Set. Participants looked at how the Dozuki platform might be used to implement a modular approach to design and assembly (using sub assemblies, sub procedures, etc.). Each procedure and each module, for instance, has a bill of materials (BOM) and its own required set of sub-procedures. Given a collection of procedures and modules, the challenge is to integrate bills of materials and instructionals for various modules. Users would identify which modules they have and which they need to create, and the app would use that information to aggregate an overall bill of materials from the discreet bills of materials for each procedure and to assemble the instructionals involved.

The first Doc Jam  delved into other aspects of open source hardware documentation as well, based on the group’s views about needs. The process of refining and promoting best practices for open source hardware documentation has only just begun. Simone Cicero sums up the work ahead for the open source hardware community: “Actually at the end of the day, all these discussions at the Jam and all these discussions [to follow] will be about, ‘Are we ok with having shared innovation, or do we prefer to compete one with each other, reinventing the wheel each time and building ten different platforms for documenting projects that don’t talk with each other?'” Simone sees the task ahead as two-fold: “Now we need to scale this to involve people from all over the world, and we need to follow up [with further work].”

For more information about the structure and format of the Doc Jam, along with links to materials and ongoing work, please check out Simone’s excellent blog post on the Jam at the OSHWA blog. Also be sure to check out our collection of short videos documenting the Jam.