Tao of Documentation

ritcheyer In November I was given the honor of speaking at RubyConf Uruguay 2011. If you have a chance in 2012 to go to a conference I would highly recommend heading to South America. All the countries work together to setup a conference tour so you can start in Chile or Colombia and work your way down to Argentina and Uruguay. The Uruguayan conference organizers are amazing. Big props to Evan, Nicolás, Pablo and the rest of the crew.

Pain

I gave a talk on how I believe it is extremely important for companies to have very detailed documentation about how to use their product and how they can make it easier for their developers to help with that process without making them feel like they are wasting their time. It frustrates me a lot when I use a product that I really like, but I cannot for the life of me figure out how to use it because documentation is non-existent. The worst is when I find out about a feature from reading another users blog post about how he/she was digging around and found this awesome hidden feature. Seriously!! I should not have to dig around to find out how to use your product.

Open source projects sadly are not excluded from this offense. I am not referring to documenting the codebase by using YARD, RDoc or TomDoc, but rather having good examples, HowTo and FAQ sections. Look at projects such as fog, Riak and Renee. Early Ruby on Rails users will remember how difficult it was to figure out all the aspects of Rails, however new users greatly benefit from the amazing Ruby on Rails guides that are constantly updated.

Journey

“Do the difficult things while they are easy and do the great things while they are small.” This quote is from my favorite philosopher Lao Tzu. Taoism is awesome and if you do not know anything about it I recommend reading The Tao of Pooh, but I digress. Engine Yard definitely did not follow Lao Tzu in this regard and we felt the pain when we decided to fix the situation. Please DO NOT start this process late. I know it seems painful, but just like with TDD writing good Documentation for your users will keep you sane and happy in the long run. Our documentation in the early days were not updated frequently at all and it was frustrating. We had setup DokuWiki and found out later on that it was not the most intuitive wiki to use, but it was better than having nothing at all. “A journey of a thousand miles must begin with a single step.” Well it took us a while, but we finally took that step and found the right tools and workflow that completely overhauled our documentation and I can proudly say that it kicks ass now.

Solution

There are a lot of tools out there that will allow you to write great documentation easily and quickly so honestly there is no excuse to have poor or zero documentation. Gollum, stasis, and nanoc are some of the many tools that you can look into using. Looking over all the tools we decided on using gollum with gollum-site that would convert the Markdown formated gollum pages into static HTML pages. We created a public ey-docs repo on GitHub so that it is easy for anyone to help contribute to our documentation. Using Markdown means that everyone who is comfortable with the syntax can clone the repo and start making changes in their respective text editor and push those changes up. Using the tools we picked allows us to easily change the style of the documentation site as well as structure the categories and pages appropriately. We even have a nice release notes RSS feed section so that our customers can be up to date on all the new updates we release to our technology stack.

Results

21 people have now contributed and we have had a 140% increase in the number of vistors to our documentation. Our guides on how to get setup to start developing with Ruby on Rails was so good the organizer of Tijuana.rb converted it to Spanish.

All Winnie-the-Pooh wants is to live a peaceful life full of joy. Shouldn’t you want the same for yourself and your users? Go create some amazing documentation.

For those of you that have your own way of writing documentation let me know about the tools and workflow you use in the comments below.

If you care to listen to the talk and see the slides here is the link: Tao of Documentation. The link to the audio is in the description section.