I enjoy giving talks. If you would like me to give a talk at your conference just get in touch.

Tao of Documentation

Slides

Most developers hate having to do documentation, yet we complain about how tools and libraries we use lack documentation. So, the question is how do you get developers to write good documentation without having to feel like they are wasting their time. There are plenty of good documentation tools out there such as TomDoc, YarDoc, and RDoc. These tools are useful for creating documentation for tools, gems and varies open source projects and each one has it’s unique way of making documentation easier for developers. However, how do you manage documentation for a product? At Engine Yard we have our AppCloud product and having good external documentation for our customers is very important to us. We want to make sure they can easily understand how to use our product and be able to accomplish what they need. However, it has been difficult to get good documentation out quickly. Since we release so many times a day sometimes new features and changes are made before documentation can even be written and pushed out. The issue prior was that we were using a tool that not many of our developers enjoyed using and therefore one person really had to find time to maintain the documentation for AppCloud. We have completely changed how we do documentation now and I believe it has helped us out at Engine Yard as well as our customers. We have moved to using an approach that allows us to push changes to our documentation site just as quickly and smoothly as we do the codebase for AppCloud.

RubyConf Uruguay / Montevideo, Uruguay / November 11 – 12, 2011