Customizing OpenStack Docs to the Communities They Serve

Doc team openstack

The OpenStack documentation team is fairly small. We’ve existed since 2012, founded by ex-Racker and writer extraordinaire Anne Gentle. Since that time, the team has moved with the OpenStack community to ensure we deliver the content wanted, in the form expected, at the time required.

Anne declared our mission to be ‘docs treated like code’ and, with that as our guiding principle, we are pleased to announce some major changes to the way we handle the OpenStack Installation Guide.

Watch Lana Brindley’s OpenStack Summit Barcelona Lightning Talk, “Turning the Install Guide on its Head: How we broke everything, for a little while” (0:00-4:30):

Before the Mitaka release in early 2016, the documentation team wrote and maintained an installation guide only 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 updated and published for every release, and one of the few books thoroughly tested before every release. This was really hard work, and so limiting the document to only those few projects was a natural way for us to keep the work under control.

Every so often, another project would ask to be included, and our standard response was to ask them to draft something in their own development repository, which would then be published to[project name]. In a couple of cases, we integrated those project-specific guides into the installation guide, but we simply didn’t have the bandwidth within our tiny team to update, maintain and test many other projects every six months.

Then along came the OpenStack Big Tent, and with it the Project Navigator, which stipulated having an installation guide on as a component of project maturity. All of a sudden, every project wanted its installation process in the installation guide, and having it on the /developer page was not going to be good enough.

The docs team needed to respond to this change. After much discussion and planning, much of it at the OpenStack Summit in Tokyo, we created a system allowing each project to write and maintain its own installation guide, in its own repository, but which we publish on the main documentation site. They sit alongside the installation guide 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 anybody.

cookiecutterWe also wanted to make the process as easy as possible, so we have this really clever little thing called cookiecutter, an open source tool written by Audrey Greenfeld, which helps projects set up a basic structure for their documents. This means there’s a consistent structure across all the documents and a uniform look across the documentation suite.

We also changed the title of the guide. That might seem trivial, but we had come to the realization that people don’t use the installation guide the way we thought they would.

As OpenStack has matured and become more complicated, it is rarely installed manually. We know from the User Survey that about two thirds of production installations are completed using Puppet or Ansible. We don’t know how many installations are completed by hand, but anecdotally we know most are done by someone hoping to learn OpenStack and its components, rather than someone setting up production systems. In other words, it’s less about the installation method, and more about learning. Accordingly, we changed the name of the basic guide to Installation Tutorial, with a focus on documenting only the 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 installation guide, which installs all the underlying services, such as networking, database and compute. From there, the additional project-specific guides build on those core services.

OpenStack documentationOf course, there’s more to be done. There’s ALWAYS more to be done! We need to keep supporting various project teams as they write their guides, and we want to redesign the installation index page to make it a little more user friendly. We also want to document other installation methods, including some of the automated systems that now exist.

For Newton, we have documented the container infrastructure management (Magnum), messaging (Zaqar), key manager (Barbican) and bare metal (Ironic) services, with more to come. Check out the Newton installation tutorial and guides here.

And if you’re working on a project you want to add to the list, here’s all the information you need to get started. 

Lana Brindley has been playing with technology since that summer in the 80s when she got eaten by a grue. She has been writing since she could hold a pencil, and wrote technical documentation for Rackspace. Lana holds Business degrees in marketing and information systems, and a postgraduate degree in technical communication. Right now, she’s raising her very own geek girl. One day she hopes to write the manual for that, too.


  1. Congratulations to the team. It’s always great to hear about what writers are doing to adapt to changing demands. The “cookie cutter” tool sounds a great idea.


Please enter your comment!
Please enter your name here