OpenStack Documentation: RTFM is A Good Thing
September 17, 2013
As programmers we often forget how important documentation is not just to each other, but especially to the people who have to use the software we create. In a massive project such as OpenStack, documentation is all that much more important, which is why there is a dedicated Documentation Team that heads up the effort to make sure that the docs are not just present and accounted for, but also useful.
In fact, the Docs team functions much like the other teams within OpenStack, even going so far as to treat the docs like code, subjecting them to the same types of code review that ensures that OpenStack is as bug-free as possible. And like other teams within OpenStack, the Docs team can always use more members to lighten the load.
To that end, this past week saw Mirantis hosting the very first OpenStack Documentation Boot Camp, designed to provide an easy way for new contributors to start working on docs, and for the old hands to get more familiar with some of the more powerful features of the documentation system.
In fact, the boot camp showed just how powerful that system can be, providing lectures on topics such as how those endless tables of REST API parameters are automatically generated, how Publican creates those beautiful PDFs, and how to use XInclude files, as well as more basic topics such as how to get started making docs patches in the first place.
More than that, the boot camp also provided an opportunity for contributors from different companies, and countries as far as Australia, to get together and meet in person, even heading down to Shoreline park to partake in some fun on the water. (Thank you, Rackspace!)
Most importantly, of course, the goal is to widen the pool of docs contributors, so for those of you who weren’t able to make it to the boot camp, we were able to videotape all of the sessions. In the coming weeks those videos will appear on Openstack.org and we’ll be making them available here on the blog, but in the meantime, we didn’t want to keep you in suspense. If you’ve been thinking about contributing to the docs and just don’t know how to get started, here are the slides from my own talk, “How to get started contributing to OpenStack Documentation”.
Continuing the Discussion