3 ways to improve your open hardware documentation | Opensource.com

3 ways to improve your open hardware documentation

Documentation is an important foundation for any open source project, to guide your community and keep it open.

Computer hardware parts
x

Subscribe now

Get the highlights in your inbox every week.

Open Hardware Month is organized by the Open Source Hardware Association (OSHWA) every October, and this year, we're putting the spotlight on ways to tell the world that your project is open source. Help support the open hardware ecosystem by bolstering your documentation in these three ways during this month.

Document

If you have a project you haven't got around to open sourcing yet, or your existing documentation could use a makeover, now is the time! Clear documentation helps potential users find, build, and potentially contribute back to your project. Adding pictures, repairing broken links, and uploading auxiliary design files are all ways of making your project more accessible.

When publishing your documentation, you'll need to specify a license since copyright applies automatically. A license such as one from Creative Commons will grant others the freedom to distribute and modify your documentation. In order to comply with the community definition of open source hardware, the license must not have a Non-Commercial or No-Derivatives clause.

Publishing your documentation can also prevent future patents by establishing prior art. If someone else applies for a patent on a similar design, your documentation could help establish your work as the original design and prevent the patent from being granted.

Label

Have you ever found a delightful project that seemed to be open source, but couldn't find a license anywhere? The Open Hardware License Label helps you declare the licenses used in your project using a format similar to the US Nutrition Facts label. Listing your licenses in one prominent place (such as the README of your repository) helps users immediately know what they can and can't do with the source, rather than having to browse through individual files. This is a helpful, though optional, compliment to the OSHWA Certification.

Certify

You've likely stumbled upon projects that advertise themselves as open source, but much of the source is curiously missing. The OSHWA Certification combats this issue (sometimes called "open-washing") by providing a way for creators whose products meet the definition of open source hardware to add a certification mark with a unique identifier. This mark gives users and customers the confidence that the product is indeed open source, and they'll be able to study, modify, and distribute the source. The certification program also provides a directory of certified projects where you can look up the details of a specific project or search for components to use in your next project. Thanks to over 200 creators, this directory recently surpassed 1,000 certified projects!

If your project is open source, you should shout it from the rooftops with pride, and documentation is actually a perfect way to do that. The more you document, and the clearer that documentation is, the more legitimacy and protection you lend to your project and its community. It helps newcomers know exactly what they're working with and ensures the project stays open. What better way could there be to celebrate Open Hardware Month?

lightbulb drawing outline

These open source components help you find ways to save money and conserve resources.
Files in a folder

Documentation is as important as code, so make sure you treat it that way. Here's how.
A pink typewriter

Documentation quality can make the difference in people trying your project or passing it by.

About the author

Eric Carlson - Eric is the Outreach Manager at the Open Source Hardware Association and fan of all things open source. He first found open source hardware through 3D printing in 2015 and continues to be involved in both open source hardware and software.