It’s that time of the new year to reflect and look for ways to keep improving the OpenStack docs. Here’s a list of major events from 2013 in OpenStack doc-land. Let’s look at the year in review.
- Operator Guide book sprint was in February 2013 and I still remember it fondly. The before post and the after post tell the tale, as does this video.
- Diane Fleming added a sidebar for navigating the every growing API reference site at http://api.openstack.org/api-ref.html. I’d like to see more improvements to the design for that page with more responsiveness for different devices.
- We have improved the DocImpact commit message flag, where developers can add DocImpact to a commit message, and some automation happens in the background to automatically log a doc bug, setting it to New until the patch actually merges, eliminating a lot of manual steps. Props to Tom Fifield and Steven Deaton for this accomplishment in 2013.
- We also were able to simultaneously release the docs with the code for the Havana release in the fall for the first time. A large part of this accomplishment is thanks to automation of the Configuration Reference, where the auto doc tool scrapes the docstrings and collects them into meaningful tables per feature per project.
- This year included a complete reorganization of the docs.openstack.org site landing page. We also added new titles to try to accommodate new audiences. We have a new user guide and admin user guide, which walk through both the Dashboard and command-line interface procedures to accomplish common tasks like launching an instance. As I mentioned above, we’re also maintaining a new Configuration Reference which lists all possible configuration options across multiple OpenStack projects.
- This year after the Summit in Portland, I worked with Lew Tucker’s finely tuned organization at Cisco to hire a contract writer dedicated to the upstream vanilla OpenStack install guide. There were still hiccups and delays despite having a dedicated resource, but the resulting install guide has been well-received.
- We held a mid-release OpenStack Docs Boot Camp in sunny California at the Mirantis office. We learned a lot from each other and got to know contributors we hadn’t met in person.
- In July 2013, the OpenStack security team put together a fantastic OpenStack Security Guide with a book sprint in an undisclosed location in Maryland. At least I think that’s where it was.They’re security conscious.
- The High Availability Guide got some refreshing as well, thanks to Emilien Macchi and Enovance test labs.
- We have Japanese fonts now supported in our tool chain, with Japanese translations now available on docs.openstack.org/ja/. Much appreciation to the translation team, especially the Japanese team lead Masanori Itoh, I18N team lead Daisy Guo, and David Cramer for the doc tooling for the font support.
- Also in 2013 we have been incubating the open source training manuals team within the OpenStack Documentation program. They’ve produced an Associate Training Guide, with outlines and schedules for an Operator Training Guide, a Developer Training Guide, and an Architect Training Guide. All guides and outlines are available at http://docs.openstack.org/training-guides/content/.
- At the Summit in Hong Kong we announced that the OpenStack Operations Guide became an O’Reilly edition and we are working on the edits coming back from our developmental editor.
- Most recently we had a Doc Bug Day on 12/20/13 squashing over 80 bugs, following the sun from Australia to the US west coast and then some.
This past year OpenStack Documentation became an official program with me, Anne Gentle, elected as the Program Technical Lead. I hope to continue to serve and promote the Documentation efforts as we go into the new year. Yes, I do read the feedback from the user survey and I know we have work ahead of us. But for the docs to be second-most complained about instead of first-most was a moment to be celebrated in 2013. Thanks to the many contributors who make these incremental improvements happen.
Leave a Reply