The power of open source hardware lies in the ability to build upon others’ work and good documentation is the key to making this happen. We believe that documentation best practices can increase contributions to open source hardware projects significantly. For this reason, OSHWA has partnered with Open Source Ecology and Everywhere Tech to host a collaborative event to arrive at an open source hardware documentation platform based on a set of shared standards. Read more about the event and register at opensourcewarehouse.org
Open product development has the potential to transform the economic system by making widespread collaboration possible. If there are easy mechanisms for viewing and updating open product documentation, products can evolve rapidly under the hands of many contributors. However, several obstacles often stand in the way of contributions and improvements. Below is a list of problems and possible ways to approach them.
- There are no unifying standards or best practices for creating high quality documentation. Beyond the excellent work done by Phil Torrone, David Mellis and Nathan Seidle for open source electronics, there is no clear description of what should be included in OSHW documentation in order to facilitate the replication, modification and repair of all types of OSHW. The internet has many disconnected pieces of open source hardware documentation, but much of it suffers in quality or clarity. Clear guidelines for taxonomy and structure can help address this. We propose an initial set of standards and guidelines to be debated and refined.
- Documentation for OSHW projects is dispersed across many platforms, websites, wikis and blogs. As the number of projects grows it’s becoming increasingly difficult to find them. We propose a taxonomy to identify both hardware and documentation modules, which may lead to an online OSHW repository.
- No clear definition of scope exists. While open source electronics has become one of the most visible facets of open source hardware, there is much more. The scope of open source hardware, and its best practices, should include items such as medical devices, houses, cars, and washing machines.
- Lack of standard formats, clear organization, and technical jargon makes it difficult for the layperson to understand existing documentation. The goal of an improved documentation platform is to enable anyone, at all levels of expertise, to study, reproduce and improve open source hardware.
- Language is a barrier for the dissemination of open hardware plans. We propose that all textual descriptions be linked to Google Translate and that a Visual Language for OSHW be developed to describe fabrication procedures – see The Noun Project and IKEA’s assembly instructions as examples.
- There’s no simple way to remix and mashup hardware. We propose a modular approach to open source hardware documentation that would facilitate remix, mashup and branching.
- Derivative work is difficult to track. Taking into account that OSHW is developed mostly by iteration and derivation, the number of branches of any successful OSHW project is significantly higher than what is typical of OSS projects. Given the proliferation of derivatives and lack of clear information about each, it has become difficult for users and developers to identify and decide what branch of a project to replicate or derive from. We suggest that a dashboard be adopted by all open source hardware projects containing essential information about each version or derivative, such as: name, brief textual description, hi-res images, hardware and software version, attribution, open source label (indicates which parts of the hardware are open source), status brief (honest description of the state of the hardware, software and documentation), changelog, dependency (what other hardware is required to run/use the hardware), compatibility (what it’s compatible with), genealogy (information on the hardware’s origins, derivatives and replications), etc. In addition to this overview about the hardware itself, we also suggest that adoption of a build dashboard containing information on difficulty level, cost, as well as time, tools, space and skills required.
- Lack of appropriate software for designing, displaying and sharing plans makes collaborative development difficult.
- It’s difficult to update and evolve open source hardware designs due to documentation dependencies – one small alteration affects several other components of the documentation.
- Documentation is time-consuming. A clean, easily accessible platform would facilitate this. If the barriers to contribution are low and a universally-understandable format is developed, then combined micro-contributions of numerous developers can make the arduous task of proper documentation tractable.
- Unclear licensing and fear of infringement of intellectual property (IP) rights discourage people from producing documentation. Documenting involves reuse of content from other sources. If people do not understand IP licenses or have little understanding of their own IP rights to use content, they may be afraid to contribute documentation. A clear how-to on open hardware documentation IP Issues, as well as a legal support framework, can mitigate this.
