Enginursday - Open Source Documentation Tools
Discussion of the OS tools we are using, and a GitHub update.
My current job here at SparkFun includes organizing documentation for our products, as well as determining what parts need to be examined for possible revisions and acting as a liaison between customer feedback and the engineering team. When I first started this job a few months ago, we didn’t have a great system in place to track changes and product suggestions from customers, or even internal changes and updates. All of our board revisions were done on our internal share drive, which made it difficult to track down who was currently updating files. There was also no notification system if things did get modified in any way. Needless to say, navigating through that system for anyone looking for particular information could be overwhelming and panic-inducing.
Because of this, we started moving all of our Eagle files and code for boards and tutorials over to GitHub, which allows us to have a trackable history on product changes and to make this history accessible to the entire community. The other great thing about this is that it allows you, the customer, to become a part of the revision cycle. You can now take our board or code files, update them, and send us a pull request with your revisions. Have a great example sketch for a sensor you want to share, that you would prefer doesn’t get lost in the forums/comments? Can’t stand the fact that a board is missing mounting holes? Let’s add it to the repo for that board! You can find out more gritty details about how to contribute and use this to your advantage on our GitHub tutorial here.
While GitHub does have a lot of great features and is accessible to anyone, it certainly isn’t perfect for us. It was originally designed to work with code and isn’t optimal for version control in regards to board design files, 3D model files or part libraries. Because of this, we are still looking to the Open Source community to see what other tools we can find to help make the sharing and distribution of our documentation easier. We want something that helps us to stay organized and on top of changes currently being worked on, and something that allows the community to access the information as needed. While we are currently collaborating with several Open Source projects, including Fritzing and Circuits.io, we are still interested to find out what other options are out there. And while we are also using tools that are freely available to the general public, such as SketchUp for 3D models, this again isn’t the most ideal tool for us, and from a lot of your feedback, you aren’t all thrilled with it as well.
A few months back, I attended the Open Source Hardware Documentation Jam along with my fellow engineer Mike Hord, and we were able to interact with several different members in the community and hear about the different tools available.
Unfortunately, the general consensus was that there are still a lot of problems with the current toolset available for sharing OSHW projects. Mike and I will also be attending the Open Hardware Summit in a few weeks (come say hi if you end up there!) to see what other tools we might be able to learn about. In the meantime however, we want to poll you! What type of Open Source tools do you use for your personal designs? Is there something we could be using to make sharing our code, board files and documentation with you easier? What can we be doing differently to make it easier for you to access the information you need?
Keep in mind that while I will be taking a look at what feedback you give, there’s only a handful of us here at SparkFun in charge of updating links and file types to share with you, so any changes may take time and there’s no guarantee that we can feasibly switch to a new toolset. But in the spirit of Open Sourcing All the Things!, share your ideas with the community! We’ll compile all of the suggested tools into a resource page for you.
