A colleague and I recently had the opportunity to attend the OpenStack Documentation Bootcamp, hosted by Mirantis in their San Francisco office. The event was provided as an opportunity for new and existing contributors to learn about the tools and processes of the documentation project. Additional time was also allocated to discussing the direction of the project and the status of the various guides being worked on for the OpenStack Havana release. Mirantis and Rackspace provided meals for the duration of the event, and several attendees also had their costs generously met by the OpenStack Foundation.
The event started out with a welcome from Anne Gentle, documentation project leader. Anne also provided the 20-something attendees an overview of the current state of the project before we dove into heavier topics such as project tooling and automation.Nick Chase also gave new contributors a very thorough walk through of the steps involved in joining the project later in the day.
Two particular highlights for me were:
- Jim Blair providing us with an understanding of the tools available for adding to and manipulating continuous integration workflows within the OpenStack project. There appear to be many opportunities for us to add simple jobs to these workflows to assist with applying higher standards to our content before it is merged into the repository.
- David Cramer demonstrating the use of clouddocs-maven and oXygen to create DocBook olink elements linking between documents. I still am not sure how we might be able to unlock this functionality in Publican in a way that scales to larger sites but I certainly have a much better understanding of the problem space and how we might handle conversion of such content to something Publican can build in the near future.
While thoroughly enjoying all of the sessions I also took a particular interest in the work Diane and Tom have been doing on automated generation of API and reference documentation respectively. These are both great initiatives ensuring thorough documentation of the various options available while allowing authors to concentrate on writing the “glue” in the form of concepts and tasks.
I myself also had the opportunity to present a brief introduction to and overview of Publican and the work I have been doing on tools to assist with using it to build OpenStack content. This was warmly received which was very encouraging. For the purposes of demonstration I presented a version of the OpenStack User Guide that had been built using Publican.
I also received a lot of positive feedback regarding the “Report a Bug” links included in some (but not yet all) Red Hat OpenStack content. There seems to be a lot of interest in enabling similar functionality for the wider project using Launchpad either in addition to or instead of the existing Disqus functionality.
All in all I feel that the event was extremely beneficial both to myself and the wider OpenStack documentation community with many of us already squirrelled away working on the tasks we discussed over the two days. No doubt though if or when there is another opportunity for a documentation bootcamp of this nature it will be even bigger and better!
- OpenStack Docs Overview by Anne Gentle
- Documentation Automation by Jim Blair
- DocBook and Oxygen by David Cramer.
- How to Contribution to Documentation by Nick Chase.
- WADL/API Documentation by Diane Fleming.
- Publishing Documentation with Publican by yours truly.
- Automated Documentation by Tom Fifeld.
- Installation Documentation by Shaun McCance.
- Training Manuals Overview by Sean Roberts and Colin McNamara.
- Anne Gentle: http://justwriteclick.com/2013/09/13/openstack-docs-boot-camp-wrap-up/
- Nick Chase: http://www.mirantis.com/blog/openstack-documentation-rtfm-is-a-good-thing/