Spree Commerce

Try It Now

Documentation Challenge

Posted on April 29, 2009 by Sean Schofield

Next week is going to be a very busy week for the Spree project. Now that things are stable enough for a release it is time we turned our attention to the issue of documentation. Documentation is a problem area for us right now and its holding us back from achieving even greater things with our project. The Rails project began a big documentation push recently and it resulted in the highly useful set of Rails Guides. This has inspired me to strive for something of this depth and quality for the Spree project.

Creating quality documentation is not very exciting. In fact, in can be outright tedious. Unfortunately its a necessary evil and with a little bit of teamwork, we can make short work of this deficiency. This brings me to the “challenge” part of this post. I’m issuing a challenge to all of our Spree community members (contributors and users) to help us finish the job. There are hundreds of you out there who have benefited in some way from the existence of this project. I am suggesting that now is a good time for you to step up and give a little something back to the community. Please consider helping us write a new guide or with the editing of the existing ones.

Many members of our community do not speak English as their first language. I can definitely understand how in this case it might intimidating to write something like this. Please consider writing something anyways and then just commit it to a fork in GitHub. You can then ask on spree-user for help to edit it for grammar, etc. We’ll take all of the help we can get.

Now for the incentive part. First, writing a guide will likely help you develop a deeper understanding of Spree. Second, quality documentation will result in an influx of users and contributors. Everyone will benefit from the increased set of features and testing that will naturally follow. Finally, if you contribute a substantial portion of a guide (or multiple guides) you will be listed on the contributions portion of the guide along with a link to your blog or place of business. So this is a good way to promote yourself and possibly to generate some business as well.

Ready to get started? The first step will be to visit the spree-guides project in GitHub. Here you will find everything you need to create and edit the guides. Just clone and run rake guides to generate them. The guides are in Textile format. Personally I’m more of a fan of Markdown but we borrowed this code from the Rails Guides and this is what they’re using. If you’re interested in contributing, please message me on GitHub and I’ll grant you direct access. This will allow you to commit directly to the official repository. Please be courteous and only use these rights to commit minor corrections or additions. If you’ve got something major to contribute, do it in a fork and let people see it before you merge it in.

We need to get this over with as soon as possible. Ideally we’ll have most of the guides completed by the end of next week. Lets celebrate the new Spree release by working together to improve the project. I’ve already worked on an overview section and I’ll be pitching in where necessary. Anyone else want to step up? If so, please state your intentions on spree-user so we can coordinate.