Hardware Reference
In-Depth Information
14.
Taxonomy of Hardware Documentation
Addie Wagenknecht
“The future is here, it's just not evenly distributed yet.”
—William Gibson
This chapter explains how to properly document your open source hardware product and
projects. It discusses setting up your documentation, structuring the community, starting the
project, and avoiding some common pitfalls of open source hardware documentation.
Successful open hardware projects depend on successful documentation. Without easy-
to-understand documentation, a project cannot be reproduced. Without reproduction, a pro-
ject cannot grow or easily be forked. The Open Source Hardware Definition requires open
documentation so that anyone may reproduce your hardware. In this chapter, we discuss
important aspects to consider when documenting an open hardware project.
One of the first questions to consider when developing an open hardware project is,
Who do you want to build it? It's important to consider the community in terms of prac-
tices, skill levels, languages, and geographical locations. For example, do you want this
project to be developed only in North America? Europe? Asia? Africa? Just at your
school's fabrication lab? It is also important to think about how users can access and find
the documentation of your open hardware project. Is it a website? A git repo? Is it search-
able by a search engine? Documentation is used as an entry point to discover a project and
determine whether it's feasible. In addition, it is important to consider writing your docu-
mentation in a way that is consistent across the project and clear enough for any user to
contribute to. Doing so enhances the project's repeatability and growth, which often trans-
lates into a larger community of developers in the long run. The goal of an improved docu-
mentation taxonomy is that it enables anyone, at all levels of expertise, to study, reproduce,
and improve open source hardware projects.
The power of open source is that it allows community members to build and progress
freely based on others' work, making advancements happen faster that might not otherwise
be economically feasible. Good documentation, in turn, is the key to progress in this com-
munity of exchange. The goal of open hardware documentation is to facilitate a framework
in which collaboration can encourage contributions, making extensions of the project pos-
sible. The easier it is to parse instructions, the easier it is to contribute new developments
toward maintaining a successful long-term project and the community around it.
