Hardware Reference
In-Depth Information
E.
Mach 30's Documentation Ground Rules
J. Simmons
We've all been there. After a long day of working in the shop/lab/makerspace/garage, we
have made amazing progress on our project, but now as open source hardware developers
we have to go back and document what we did. Fellow developers are waiting on the doc-
umentation to continue their own work. Fans are waiting so they can follow along at home.
And, the very definition of open source hardware means we aren't really done until we have
written sufficient documentation so that someone else can recreate our work.
What a chore! What a pain!
Mach 30's documentation ground rules help ease this pain by building documentation
into the process. Lessons from projects like the Shepard Test Stand and Ground Sphere
ground station have taught us it is much easier to capture documentation as we go along
than to come back and do it later.
1.
Every project needs a home (for its documentation).
Start project documentation as soon as you have the idea for a project. Capture its
purpose, your general design concept, the budget, and other details right from the
beginning. At Mach 30, we have an understandable preference to use Open Design
Engine for hosting our projects. Open Design Engine is a one-stop project-hosting
portal that is free for open source hardware projects. Its users can add wikis, forums,
source code repositories, and more with just a couple of clicks, making Open Design
Engine a strong choice for projects of all types and sizes. Of course, there are sever-
al other sites to choose from, and in a pinch, even setting up a folder in Google
Drive will suffice to get things started. Our experience has shown that it is much
easier to expand existing documentation than to port it from one location/format to
another. In your project development, you should find what works for you and start
even small projects in your preferred solution. That way, projects that grow beyond
your expectations are already in fertile soil and don't need to be transplanted.
2.
Document before you act.
As soon as you make any decisions about a project, write them down. If you have an
idea about which embedded processor board you want to use in your next project,
start your preliminary design document and your bill of materials. If you're getting
ready to go shopping for parts (online or offline), create a draft BOM and do your
shopping based on its contents. Even if there are items for which you have only a
