A common complaint about many open source projects is documentation. Insufficient, incorrect, non-existent, hard to find, and difficult to update are things we typically all hear. There are a lot of different ways to tackle these problems. There's no silver bullet but one of my favourite tactics is lowering the barriers for absolutely anyone to walk up and contribute documentation.
Lowering the barriers means:
I built a system for the Apache jclouds community that lowers these barriers. But before getting into the details of exactly how I implemented this, let's take a look at the process of actually making a contribution.
There are 3 actors in this process:
This is the process they go through:
While this might seem like a long process, it can actually be very quick. The process could happen in less than 5 minutes, if a simple edit required no additional changes and the reviewer signed off right away. It‘s important to note that there is no incidental complexity here. The process is as efficient as it could possibly be with respect to GitHub’s workflow.
Here's how I implemented this doc system in the jclouds community.
Many people have GitHub accounts already and getting one is trivial. It also gives the jclouds community a good idea about who is making the contribution. The pull request is the primary unit of collaboration on GitHub.
Simple Markdown documents with HTML/CSS make up the content of the jclouds website documentation. They are combined using Jekyll, a template engine, so that contributors can focus on the content and not the layout of the entire website.
It doesn't get anymore ubiquitous than the web browser. The Markdown documents can be edited in a textarea on GitHub from a web browser. The web has trained us to fill out online forms and this is no different. You could just as easily go through the process above on your mobile phone.
Jenkins, at the heart of the doc system, is responsible for building the website with Jekyll and uploading the staging jclouds website to Rackspace Cloud Files using jclouds. Installation and configuration of Jenkins itself is outside the scope of this post but it's relatively easy to get started using it. You need the GitHub Plugin and configure a webhook to fire when a pull request is made to your GitHub repo.
Jenkins jobs are what get the work done in the jclouds doc system. The 2 jobs are:
Execute shell 1:
More relevant settings:
Execute shell 1:
Execute shell 2:
The jclouds community actually uses CloudBees extensively as the place to host our Jenkins jobs. However, these jobs have been generalized and should run on Jenkins with the GitHub plugin.
This isn‘t just about documentation; it’s about building community through contribution. If you can get a user to make a documentation contribution, that user will be much more engaged in your community. They will have feeling of ownership and pride in a piece of software that they depend on and that they have improved. These are the users who will be with you through thick and thin, and who will find other ways to contribute to your project.
You might not be able to implement this system exactly as I‘ve done it in the jclouds community but the important part is finding ways to lower the barriers to contributing documentation. I didn’t build this system in a day. Tackle each of the barriers above one at a time. Eventually you'll be able to put the pieces together into a system that works for you.