Writing the OpenStack Operations Guide

The first edition of the OpenStack Operations Guide was written during February 2013, by seven people: Tom Fifield, Diane Flemming, Anne Gentle, Lorin Hochstein, Jonathan Proulx, Everett Toews, Joe Topjian, and facilitated by Adam Hyde. The second edition, edited by O’Reilly and available now, had over fifty contributors who added to it, logged issues, and reviewed updates.

In a conversation with Anne Gentle, OpenStack Documentation Program Technical Lead, we learned why the team undertook an ambitious book sprint, and how it has become a model for community-developed guides and manuals.

While the OpenStack community was hungry for an operations guide, the experts in operations were simply too busy to write comprehensive documentation. As a result, several community members brainstormed a creative solution to the dilemma, and pulled together a team of seven individuals with experience building and managing OpenStack clouds to co-author a book. If they could get a weeklong, focused chunk of time from each of the operators in one room, they hoped to get the content flowing.

It started with Everett, who recruited his former colleague from Canada (Joe) who manages the first Canadian OpenStack cloud at Cybera (which Everett helped implement). Then Everett, who also worked for a few weeks in Australia to get its first OpenStack cloud off the ground (NeCTAR), brought his peer Tom onto the team. Add to this group Anne and Diane from Rackspace, as well as Lorin, who were all regular contributors to the OpenStack documentation team. Finally Anne recruited Jon, who operates an OpenStack cloud at MIT, after meeting him at an OpenStack Summit.

The team flew in from around the world and gathered at the Rackspace offices in Austin, Texas. According to Anne, a book sprint is long hours and “intensely collaborative,” so it was fortunate the team got along and worked well together.

On the first day of the sprint, Adam Hyde walked the team through the sprint process. They started off by writing topics on sticky notes. Once they had the architecture of the book defined on these sticky notes, they started to write. As Anne put it, they wrote one note at time, writing the chapter title, then the chapter, revising as necessary. What’s important to note is that they wrote from their real experiences so they already had a lot of information in their back pockets (wiki pages, training guides, etc…) ready to plug into the book.

The actual writing process took three and a half days, and produced over 10,000 words per day. The last day and a half was spent editing and polishing. Hyde guided them through the entire process helping organize the team, their ideas and their content.

w9c3m9sfcj7utnmcg2kz

The OpenStack Operations Guide is written for someone running OpenStack day-to-day. Part one is all about planning and decision making, featuring a pair of example architectures that include the primary OpenStack projects. The authors chose the two architectures because they had experience running them in production on thousands of nodes. Part two of the book talks about the “first 90 days of your cloud”, and is oriented around ongoing operations.

When the book came out, Anne was contacted by several cloud architects who liked the book, but felt there were many more considerations for designing an OpenStack cloud. Generous feedback from the community which has spawned updates to the original book, as well as additional guides and in-depth content.

After the book sprint, the team was curious to see how much community they would build around the book, and have since been delighted to have 50 contributors. Most people noticed small fixes, or asked for additional information on a particular topic. So while the book has been published, we’ll continue to see updates and additional supporting documentation.

It just so happened that O’Reilly publishing was looking for a book that covered OpenStack operations, and they reached out to OpenStack late 2013 after hearing about the book sprint and success of the Operation’s Guide. O’Reilly has a great reach for getting the OpenStack story out, plus they understand the community model and open source licensing, so they decided to publish the next generation of the book through them.

The team got together for another mini-book sprint in January 2014 to update the content and add a few new pieces, such as another architecture running Red Hat and OpenNet networking.

The book is available for free from OpenStack, and community members are encouraged to contribute to it. If you would like to order printed copies in bulk, you can also purchase the O’Reilly version of the book.

aoep8rtgvtbivfvwymxw

The Operations Guide book sprint had a big impact on the community. Anne explained how it has even spurred other community members to do additional book sprints based on their subject matter expertise. For example, in June of 2013, the security team ran a book sprint over five days producing a 240 page book about securing your OpenStack. A third one that will start in July 2014, will expand on some of the design and architecture concepts from the first half of the Operations Guide, focusing on very specific use cases for topics like storage and compute architectures.

Hear the authors talk about the book sprint in their own words below.

http://www.youtube.com/watch?v=mw-e5D6PwXM