Rory Aronson On Documenting Open Source Projects

Every project starts off with an idea. Sometimes those ideas are bigger than one person, or even a small group of people. That was the position [Rory Aronson] found himself in with Farmbot, his finalist entry in the 2015 Hackaday Prize. Documentation was key for [Rory]. Farmbot first came into the world in the form of a white paper. The paper included a request for collaborators, making this an open source project from day 0. Documentation has been important throughout the Farmbot project, so it was naturally the topic of [Rory’s] talk at the 2015 Hackaday SuperConference.

Rory’s mission statement is that “Great documentation is a fun, thorough, and concise dialogue that distributes knowledge”. He’s right of course. Anyone can pick out terrible documentation. It’s either too long, too short, out of date, or just plain wrong. [Rory] strives to keep documentation short and to the point with the Farmbot project. He’s not the only one working on it – that’s the ‘dialogue’ part. Farmbot has a forum and a community driven documentation site which makes the documentation easy to keep up to date.

No one likes writing documentation – it’s just not as much fun as jumping onto the next project. The reward is in inspiring people to work with you, to build upon the foundations you’ve laid down. It often helps to have some humor while you’re in the middle of documenting a project. That’s where the fun comes in. For [Rory] fun took the form of a few puns, meme images, and his trademark thumbs up photo at the end of every assembly step. Check out [Rory’s] video after the break, and give us some of your documentation tips in the comments!

7 thoughts on “Rory Aronson On Documenting Open Source Projects

  1. What he said about documenting was tight on. IMO some of of the HAD .io links the hackaday staff point to would do well tho take this to heart. Then agai it could be however it could the HAD. io structure that makes it difficult do great documentation. I have never used it so I can’t know. Respectfully as farm bot goes, I can’t see it nothing more that a first world back yard gardening gimmick. In the event if that what it’s for some busy to have successful gardens that’ great. Anyone anywhere whose nutrition needs depend on personal production will find the time to check the crops multiple times daily to make adjustments as needed. Those same persons may not have affordable internet resource to participate in open source project development and documentation. Here in the US there is commercial farm bot like technology in being use by farmers.Part of the Americans mytholgy that farmer repair or build there own equipment. In my experience many do, but more elect to pend that time on income producing activity on or off the farm. I wouldn’t expect many US farmers to participate in free and open source hardware as an alternative to what may available commercially. To close I can’t find much to fault about what he sain regard to actual presentation topic.

  2. I wish hackaday.io would look more like a normal webpage (like the readme.io Rory shows), with customisable links on the left (introduction, materials, blah1,blah2..1st prototype, conclusions) to subpages. Now Hackaday.IO it’s just one big scrollable log. It’s a bit like reading a book without having pages. Especially for bigger logs this gets tedious very fast. That in a way is an example of having documentation that is not concise.

  3. Great talks on the Open Source sharing concept Rory (thumbs up)
    Listening in on your talk has given us here at OpenBuilds some new ideas and insights on helpful features that we can implement into the OpenBuilds site. Thank you for sharing.
    Looking forward to watching the FarmBot continue to progress.

Leave a Reply to OPENBUILDSCancel reply

Please be kind and respectful to help make the comments section excellent. (Comment Policy)

This site uses Akismet to reduce spam. Learn how your comment data is processed.