Good documentation is critical for any open-source project. Be it hardware or software or both, good docs help others understand the design intention, how to navigate the project, and how to go about making modifications. Without good docs, the project might as well be closed source.
Up until today, we've been posting our docs in several places. Hardware docs were hosted here on go.farmbot.it, and also on the community wiki; while our software was docs were hosted on GitHub. The problem with hosting hardware docs on a wordpress site or on a wiki is that neither platform is particularly suited to making or presenting good documentation. This makes for some pretty ugly looking docs that are somewhat painful to create. Software docs on GitHub are great for stuff like: How to setup and run the software, but not so good at teaching software developers how to use an API, or the inner workings of a codebase, or how to go about modifying and extending the software. For a while, we've been needing a better solution for both hardware and software docs.
A few months ago we stumbled across a new documentation service called readme.io
. Its a pretty new service aimed at creating beautiful docs and developer hubs, and we're giving it a shot. So far, we're very impressed with its ease of use and the beautiful docs it creates. What's great about it is that it works well for both hardware and software, and it allows us to easily create new documentation versions based on old content. Plus, they are very supportive and generous in offering open-source projects free service!
So today we're announcing two new documentation hubs:
farmbot-genesis.readme.io is our new home for all documentation for FarmBot Genesis including change logs, design intention, assembly instructions, maintenance advice, and software setup
farmbot-software.readme.io is our new home for documenting the web application and API, farmbot-serial, farmbot-arduino-firmware, and the farmbot-raspberry-pi-controller
Note: Both are still works in progress!