Havana Pumps Up the OpenStack Docs Suite, Brings Cloud Admin, Security, and Training Guides
OpenStack’s Havana cycle gave life to two new services, Metering (Ceilometer) and Orchestration (Heat), and introduced copious improvements to each of the existing core services. Sitting quietly at the end of the Release Notes are changes to the OpenStack Documentation.
These changes in fact are colossal, which is quite obvious when you compare the before and after shots of Grizzly with Havana states of OpenStack docs.
Grizzly Docs
Havana Docs
There’s so much to talk about here (and we will further on), but we wanted to draw your attention first to a guide that borrows something old and brings in something new. The administration guides for several different services have now been merged into a single Cloud Administrator Guide. If perhaps you’re wondering what happened with the information on how to configure Identity Service for Networking you used to see in the Networking Administration Guide, check out the Cloud Admin Guide’s Networking chapter.
In addition to this merge, the Cloud Admin Guide has been absorbing configuration instructions from the Configuration Reference since the end of the Havana cycle to make the guide meatier and reduce the latter to a collection of automated reference tables for a better usability. Further, chapters are also being updated for the latest fixes and features in each of the services and are undergoing substantial edits for flow and comprehension, thanks to contributors from Mirantis, Rackspace, Red Hat, and other participants.
Perhaps the most intense change in the OpenStack Documentation news is the overhaul of the Install Guides. They’ve been rewritten and taken shape of a "choose your own adventure" guide. They walk you through the basic operating system configuration, explain how to configure the Identity, Image, and Compute services and install Networking, and then they show how you how to add other services for each distribution option.
Another major highlight is the upcoming publication of the Operations Guide by O’Reilly. The guide, written in the sprint mode over the course of mere five days, is going through the developmental phase and is expected to be published in April. Back in October, when this news broke out, Rackspace Content Stacker and OpenStack Docs PTL Anne Gentle said, “This is an exciting experiment for us to take a book written in a five-day book sprint and have it undergo professional editing, indexing, and delivery methods.”
The issue of security compliance in OpenStack implementations necessitated thorough coverage of cloud security concepts and scenarios. The Security Guide is another sprint book accomplished since the Grizzly cycle and it brought together some of the most prominent cloud and systems security experts from Cloudscaling, CloudPassage, HP, Intel, Johns Hopkins University, Nebula, NSA, Rackspace, Red Hat, and VMware. The guide lays down the foundations of security boundaries and threats. It’s peppered with case studies involving public, guest, management, and data domains with various threat actors.
A new Docs component that’s going to be crucial for learning OpenStack comprises a set of Training Guides that corresponds to associate, operator, developer, and architect roles in cloud implementations.
“We have had a great mix of community and commercial engagement, with Aptira making significant contributions of intellectual property to the course, as well as significant investments of time an effort from Yahoo, Nexus, and most importantly dedicated individuals in the community,” said Colin McNamara, Chief Cloud Architect for a Nexus IS and OpenStack Ambassador. “And while there is much more work to be done, I am extremely proud of the fact that we have come together as a community to address the need for training and enablement around OpenStack.”
And community involvement is pivotal to making OpenStack Docs bigger and better. Anne appeals to all of the current and potential contributors reading this post to begin working on icehouse docs to meet the March 27 release candidate.
If you’re interested in helping, review the manuals and help whip them into shape. Each page has a bug icon you can click to let you report a bug. Also, take a look at the list of existing bugs, and fix them or offer solutions. If you’ve not contributed before, follow these steps to sign up, and these steps to contribute. If you’ve contributed code but not to the docs, you’ll see that the docs are treated just like code, with identical commit, review, and merge procedures. We hope to see you there.
