Turning the OpenStack Install Guide on its head

OpenStack Documentation project team lead (PTL) Lana Brindley will be giving a lightning talk on the Install Guide at the Barcelona Summit, here’s a preview of what’s new.

This story begins, as so many do, with an argument on a mailing list. Before Mitaka, the documentation team only wrote and maintained an install guide for what was then referred to as the ‘Defcore’ projects: Nova, Glance, Keystone, Neutron, Cinder, Horizon, plus a couple of others. It was one of the few books where we published a new version with every release, and it was also one of the few books that was thoroughly tested before every release. This was really hard work, and so having the document limited to only those few projects was a sensible way for us to keep the amount of work required under control.

Of course, every so often, some other project would ask to be included in the book and our standard response at the time was to ask them to draft something in their own development repository, which would then be published to docs.openstack.org/developer/[project name]. In a couple of cases, we did eventually integrate those project-specific guides into the Install Guide, but we simply didn’t have the bandwidth within our tiny team to update, maintain, and test too many projects every six months.

And then along came the Big Tent, and with it came the Project Navigator, which stipulated having docs on docs.openstack.org as a component of project maturity. All of a sudden, every project wanted their installation process in the Install Guide, and having it on the /developer page was not going to be good enough.

It wasn’t too long before these feelings simmered up onto the mailing list and things reached a head about a week before the Mitaka release went live. So it became the topic of the moment at the Austin Summit, some really good ideas were thrown around, and by the time the week was over, we had a plan!

Together, we got things set up in such a way that each and every project can now write and maintain their OWN install guides, in their own repository, but then we publish them all up to the main docs site and have them sit alongside the Installation Guide that we already have, in a way that makes them all look the same. In this way, we can treat all projects as first class citizens within OpenStack and we don’t have to say no to anyone.

We also wanted to try and make it as easy as possible for projects to do this, so we have this really clever little thing called cookiecutter, which is an open source tool written by Audrey Greenfeld. Our implementation of cookiecutter helps projects to set up a basic structure for their document. So there’s a consistent structure through each individual document and it looks uniform across the docs suite.

One of the other changes we made was to the title of the guide. Now, that might seem trivial, but we had come to the realization that people didn’t use our Installation Guide in the way we thought they would. As OpenStack has matured and, yes, become more complicated, it’s become unusual to install it by hand. We know from the User Survey that about two thirds of production installs are completed using Puppet or Ansible. We don’t know exactly how many installs are completed by hand, but anecdotally we know that most manual installs are done by someone hoping to learn about OpenStack and its components, rather than setting up production systems. In other words, it’s less about the installation method and more about learning. Accordingly, we decided to change the name of the basic guide to Installation Tutorial, and focus on only documenting manual processes.

In summary, as of the Newton release, newcomers to OpenStack have a much clearer path to getting started. There’s the basic, core install guide, which gets all the underlying services installed, such as networking, database, and compute. From there, the additional project-specific guides pick up from that base first step, and build on those core services.

Of course, there’s still more to be done. There’s ALWAYS more to be done! We need to keep on supporting various projects to write their guides, and we also want to redesign that index page to make it a little more user friendly. We also want to get some other install methods documented, including some of the automated systems that now exist.

For Newton, we have Container Infrastructure Management service (Magnum), Messaging service (Zaqar), Key Manager service (Barbican), and Bare Metal service (Ironic) all documented, with more to come.

Read the content at http://docs.openstack.org/project-install-guide/newton/
And if you’re working on a project you would like to add to the list, get all the information here: http://docs.openstack.org/contributor-guide/project-install-guide.html

https://www.flickr.com/photos/icedsoul/2624988907/

// CC BY

Tags: Newton, Tools, tutorial