We didn’t have to do pushups to get the wifi password, though I did consider that requirement for our boot camp theme and decided, no calisthenics required. We gathered about 20 writers and developers who wanted to learn about OpenStack documentation in the Mirantis training room for two days this week in Mountain View, California.
The idea for a docs boot camp came from the OpenStack Infrastructure team who held one back in June. We wanted to enable more people to contribute to OpenStack documentation through in-person training and team building. It’s not like a book sprint, with the goal of a book in five days, but rather a training session, with questions and answers in real time.
We even had a schedule! And presenters! With labs! We also held an unconference each day in the afternoon. As presentations sparked ideas for further discussion, we wrote them down on notes and everyone could vote on which ones to discuss further during unconference time.
Day one I gave an overview of OpenStack Documentation to give people the history and more context for how we follow development processes.
Jim Blair from the infrastructure team gave an overview of how doc builds work and how we can make templates for our doc build jobs. Since the openstack-manuals repo recently went through a restructure for simplicity (Sunday we were still merging!), this was very timely information. We ran through a lab to make a Jenkins job with a yaml file and also talked about our gating jobs and how to improve them to give better results in the content.
David Cramer, our Maven clouddocs-tools plugin maintainer, did a presentation about DocBook and the newly added support for
olinks, a mechanism that allows for easier link management.
After lunch and a walk to a local park on the other side of a satellite Google office, we switched the schedule a bit to have Nick Chase tell us how to contribute to OpenStack documentation — by showing the onboarding process and how to commit a patch to openstack-manuals. We also had an unconference session about how to get new writers hired at different companies going with good projects.
Basically, read the OpenStack docs! Report doc bugs! Triage some doc bugs! Edit based on our conventions and standards including proper spelling! Fix those pesky doc bugs! Get paid! Win!
Monday evening we enjoyed boating and dinner at Shoreline. Ahh. I also followed a Google self-driving car onto the Google and LinkedIn campuses! Fun.
Tuesday morning we were back at it, and I finally remembered to go around the room for introductions. We had doc-loving representatives and training enthusiasts from Cisco, HP, Mirantis, Nexus IS, OpenStack Foundation, Rackspace, RedHat, SwiftStack, and Yahoo!
Our next technical topic was a talk about API documentation with WADLs with Diane Fleming. I still marvel at the great output we can get from WADL, and especially appreciate how much work it takes to maintain accurate request and response samples. Diane has fixed literally over 100 doc bugs since she started working on OpenStack docs last year. She’s an amazing doc contributor.
Next we got all geeky about doc tools again with a presentation and demo of Publican from RedHat writer Stephen Gordon. I asked a ton of questions about their authoring processes, such as “do your writers write differently since they write “articles” instead of book “chapters?” Fascinating look into the world of all-open all the time. They are making the upstream OpenStack docs even better so their own customers get better docs.
Before lunch, Tom Fifield gave a presentation about the autodoc tool that is now working great for scraping the configuration options and putting them into the OpenStack documentation. It’s really amazing, we’re able to document over 1500 configuration options and keep up with code like never before. It’s still a manual, human-must-read process to make sure our groupings for configuration options are correct, but this autodoc tool is a really cool tool that we can keep iterating on.
After lunch, Shaun McCance talked about his plans for consolidating the Install Guides into a set of “choose your own adventure” style books. Michael Still and I had to attend the Technical Committee meeting so I had to miss out. The adventures are in an Etherpad and Shaun has six weeks to get this adventure done! Go go Shaun.
I think we all had a good time together, finding like-minded docs people, creating relationships with training-minded people, and solving some docs problems all in real-time. Thanks so much to Mirantis for hosting and feeding us so well, much appreciation to Rackspace for sending us and giving us such a fun adventure Monday and delicious Dish Dash Tuesday, and great gratitude to the OpenStack Foundation for supporting two travel grants and supporting fine folks like Tom Fifield, Stefano Maffulli, and Jim Blair. We can go forth and rock more docs!