community techpubs work writing

OpenStack Operations Guide Mini Sprint


We held a two-day mini-sprint in Boston at the end of January to update the OpenStack Operations Guide. You may remember the first five-day sprint was in Austin in February 2013. This time, the sprint was shorter with fewer people in Boston and a few remote, but we had quite specific goals:

  • Update from Folsom to Havana (about a year’s worth of OpenStack features)
  • Roadmap discussion about nova-network and neutron, the two software-defined networking solutions implemented for OpenStack
  • Add upgrade instructions from grizzly to havana
  • Implement and test the use of parts to encapsulate chapters
  • Address editor comments from our developmental editor at O’Reilly
  • Add a reference architecture using RedHat Enterprise Linux and neutron for networking

Some quick wins for adding content were:

We added and updated content like mad during the two days:

The two toughest updates are still in progress, and our deadline for handover to O’Reilly is this Wednesday. The first tough nut to crack was getting agreement on adding an example architecture for Red Hat Enterprise Linux. We are nearly there, just a few more fixes to go, at The second is testing the upgrade process from grizzly to havana on both Ubuntu and RedHat Enterprise Linux. That’s still in progress at

The next steps for the O’Reilly edition are proofreading, copyediting, and indexing over the next six weeks or so. I’ll be keeping the O’Reilly edition in synch with our community-edited guide. As always, anyone in the OpenStack community can contribute to the Operations Guide using the steps on our wiki page. This guide follows the O’Reilly style guide rather than our established OpenStack documentation conventions. I’m looking forward to a great future for this guide and we’re all pretty happy with the results of the second mini-sprint.

Thanks to everyone making this a priority! Our host at MIT was Jon Proulx joined by Everett Toews who braved airport layovers and snow, and Tom Fifield who wrote the most patches despite a complete lack of sleep. Joe Topjian worked on edits for months leading up and has been tireless in making sure our integrity and truth lives on through this guide. Thanks too to the the hard working developmental editor at O’Reilly who offered lunch in Boston, Brian Anderson, joined by Andy Oram. David Cramer got DocBook parts working for us in time for the sprint. Summer Long worked long and hard on the example architecture for RedHat. Our remote reviewers Matt Kassawara, Andreas Jaeger, and Steve Gordon were so valuable during the process and ongoing. Shilla Saebi gave some nice copyediting this past week. What an effort!

community content strategy techpubs tools

A Few of my Favorite Things for 2013


This year has been filled with interesting finds, discoveries, and productivity. Plus oxford commas! Here are my favorite things for 2013.

The Hunger Games trilogy, because it’s like a window into a mind of a smart writer who writes with purpose.

The Documentation chapter of the Developer Support Handbook has to be one of my very favorite things I discovered this year. I’m on the Developer Relations Group team at Rackspace and this is a great handbook for all of our team.

Animated GIFs, pronounced jifs, am I right? OpenStack Reactions cracks me up.

Grace Hopper Conference by the Anita Borg Institute, especially the Open Source day, and the GNOME Outreach Program for Women which OpenStack started participating in this year. Women in technology are my favorite!

The Houzz App on my Android tablet for eye candy while messy remodeling was actually happening. Plus it’s the best content remix site I’ve seen in a while, more targeted than Pinterest.

Photo kids

Probably the best photo of my kids this year, I make it a favorite because at their ages it’s difficult to get one of the both of them.

OpenStack Docs Boot Camp

OpenStack Security Guide book sprint, read it at


OpenStack Operations Guide book sprint, now an O’Reilly edition, read it at

How about you? What are some of your favorite things from this past year?

techpubs work writing

Who Wrote OpenStack Havana Docs?

I know, I know, OpenStack is too obsessed with statistics for contributors. I agree! I want to rise above it but the trend release-over-release for docs is way too tempting for me in my research lab for documentation. So allow me to indulge in some analysis that is similar to my post about this last release, Who Wrote OpenStack Grizzly Docs? Remember? We had 79 docs contributors overall, with 3 of us writing half of the changes for Grizzly. This time we had 130 docs contributors with 7 of us writing just over half the changes in overarching install/config/deploy/operations guides. Progress! We also had at least three supporting companies hire writers dedicated to OpenStack upstream docs. Full of win. I love having OpenStack job postings to offer great tech writers.

Worcester Terrace

We added 100,000 lines more than last release. What? Yes, it’s true. Much of that is from our autodoc efforts, pulling all 1500 configuration options directly from the code, but that’s a compelling number to share.

I ran the same scripts as last time to maintain consistency. All these stats are from the tools that aren’t being maintained any more from openstack-gitdm.

Here are the numbers for the openstack-manuals repository only:

Processed 966 csets from 130 developers
92 employers found
A total of 187524 lines added, 275056 removed (delta -87532)

Developers with the most changesets
 Andreas Jaeger 233 (24.1%)
 annegentle 89 (9.2%)
 Tom Fifield 70 (7.2%)
 Diane Fleming 70 (7.2%)
 Christian Berendt 65 (6.7%)
 Sean Roberts 44 (4.6%)
 Stephen Gordon 41 (4.2%)
 Summer Long 21 (2.2%)
 Lorin Hochstein 20 (2.1%)
 nerminamiller 17 (1.8%)
 Gauvain Pocentek 15 (1.6%)
 Emilien Macchi 15 (1.6%)
 Colin McNamara 14 (1.4%)
 Shaun McCance 13 (1.3%)
 Deepti Navale 11 (1.1%)
 Phil Hopkins 9 (0.9%)
 Aaron Rosen 8 (0.8%)
 Kurt Martin 8 (0.8%)
 Scott Radvan 7 (0.7%)
 Edgar Magana 7 (0.7%)
 Covers 80.434783% of changesets

This is another interesting data set:

Employers with the most hackers (total 136)
Red Hat                     12 (8.8%)
IBM                         12 (8.8%)
Rackspace                    8 (5.9%)
HP                           7 (5.1%)
Nicira                       4 (2.9%)
Mirantis                     4 (2.9%)
SUSE                         2 (1.5%)
Yahoo!                       2 (1.5%)
eNovance                     2 (1.5%)

I also ran these same stats for the api-site repository, where the API user docs are sourced. These docs are still quite different from a contributor and sourcing standpoint and I’m not sure why. Rackspace dedicating Diane Fleming has made a huge difference here, think of what we could do with one more dedicated API doc writer? Ok, we can’t clone Diane, but think of the possibilities.

Developers with the most changesets
Diane Fleming 46 (58.2%)
annegentle 5 (6.3%)
Cyril Roelandt 2 (2.5%)
Kersten Richter 2 (2.5%)
Brian Rosmaita 2 (2.5%)
Rupak Ganguly 2 (2.5%)
QingXin Meng 2 (2.5%)
ladquin 2 (2.5%)
dcramer 2 (2.5%)
Employers with the most hackers (total 23)
Rackspace 5 (21.7%)
IBM 5 (21.7%)
Red Hat 2 (8.7%)

I’m also a web analytics hound. What docs were the most accessed during the lead-up to the Havana release? Here are the top five:

  1. Swift Developer site
  2. Install Guides (Basic and Deploy, both Ubuntu and RedHat/Fedora/Centos)
  3. API Quick Start
  4. OpenStack Operations Guide
  5. Getting Virtual Machine Images page from the OpenStack Compute Administration Guide

To me, these stats show that we’re doing the right things such as dedicating a contractor to the install guide. Thank you Cisco. We still have areas to improve, such as API docs and ensuring end-user docs are a top priority. Our readers are definitely after both deployment and consumption of OpenStack clouds.


Reflecting on the OpenStack Summit in Hong Kong

We have come such a long way since November 9, 2010, when I attended my first-ever OpenStack Summit in San Antonio Texas. I couldn’t pronounce Vishvananda Ishaya’s name, I kept interchanging swift and nova code names, and I could hardly remember two Linux commands in a row. But I got some great t-shirts, kept asking questions, got answers from encouraging co-workers and community members, and I learned as quickly as I could. Fake it ’til you make it, right? Fast forward three years, and we come to the first non-US-based OpenStack Summit in Hong Kong, my seventh. Here’s a summary of my favorites.

Dragon welcome dance

What else would we do to get ready for the Summit on the other side of the globe than be welcomed by two dancing dragons! This was a perfect start to the week.
Dragon dance opening

Summit 101 session

I helped with the OpenStack Design Summit 101 again this time, where we let newcomers know how the sessions go, what to expect, how to get the most out of the sessions. Loïc Dachary, Thierry Carrez and I talked about what PTLs want to get out of the summit, how blueprints work, and fielded good questions, all of which are Q&A on Here are a couple, see the Etherpad for more.
Q: Is the idea to discuss one specific blueprint?
A: More generally, how to we do X, and what blueprints are required to do that. Depends on the session, what blueprints already exist in the area, impact on multiple projects, etc.

Q: Do we make decisions about the specifics of the design?
A: Again depends on session, some session leaders will want a recorded decision as the outcome of the session. At the very least at the end of the session aim to know what the next step is.

If you’re curious, this is pretty much what design summit sessions look like. We intently read the Etherpad displayed on the screen, and if you sit forward, it means you have something to contribute to the discussion.

In an Infra session

Install guide, unleashed

Midweek, I had to make an observation – we’ve never had a working install guide at the Summit until Havana, and the fact we have one has been super helpful for getting it tested. There were doc comments overnight each day of the Summit. I told the docs team through the mailing list:

We need to be sure we are keeping up with the changes to the install guide by fixing what people tell us is wrong. Let’s make install guide bug fixes top priority for the next week to capitalize on all the testing that has come in.

Also, please update For example, there are doc comments confirming a page works on 13.04. We need to ensure that’s captured in the wiki page so we have an accurate assessment.

Thanks all for the work on the install guide — it is paying off, let’s take the time to clean up what’s being tested.

Sure enough, we have merged in over 50 changes in a week, complete with backports to ensure the Havana install guide gets better and better.

Meet the Technical Committee

One of the highlights of the week was the opportunity to sit on the big stage with my fellow technical committee members. We answered prepared questions from Thierry Carrez, and also queries from the audience. One audience question I didn’t jump on is at 32:40, “… you’re representative of your communities, we are in China, but there is no Asian on the podium. What can you do to actually try to improve the situation?”

John Griffith answered, it’s a matter of who has contributed, and who wants it badly enough to do the work and lead the way. Michael Still said, “You have to be in it to win it,” and noted that Beijing had the highest number last release, but it’ll take time for contributors to self-nominate and run for a spot. Mark McClain noted that as a contributor from Ireland, he has faced the facts as well that he’s in a region with fewer contributors, but he acknowledges how much our understanding of a meritocracy is cultural, and that it’s not shared by everyone. We have to talk about diversity because we don’t have a massive amount of it. I agree that it’s not easy, and I know what it means to feel underrepresented. I think outreach is a great path forward, and I’m dedicated to it for women. I’d love to see more outreach to other communities and learn from them the cultural norms that we can take to the TC and keep working on diversity. It’s a marathon and not a sprint, that’s for certain. We can get better as a community, though, and we need to iterate on ideas all the time. Glad it was brought up in this forum.

Meet the OpenStack Technical Committee

OpenStack Operations Guide

We announced the O’Reilly Early Edition of the OpenStack Operations Guide last week. I had some fun on Twitter trying to get people to guess the animal on the cover. I blogged about it on the OpenStack blog, take a look.

Hong Kong itself

The most incredible thing about OpenStack Summits is all the stackers there together. I never had trouble finding people to go sightseeing with. Here’s the one sightseeing day I had, going on a “crystal bottom” cable car ride to get to a big Buddha statue with a monastery nearby with my teammate Everett Toews, whose write up is on his blog.


We went to the Night Market one evening to buy gifts and eat super fresh seafood. 

All in all it was an amazing trip and another great Summit. I’m so grateful to the OpenStack Foundation and Rackspace for making it happen for me for the seventh time. Feels like a lucky Summit.

community wiki work writing

Game Changers: Rackspace supporting Girlstart here in Austin

Creative, brave, resilient, these are all words we cherish for our daughters, our best friends, our coworkers, all those who have faced any sort of technical or scientific challenge and wondered if they were up to it. Rackspace sponsored at table at the GirlStart Game Changers Luncheon yesterday and we managed to overflow one table to another. We had a great time!


Girlstart is an Austin-based organization that offers after-school and summer camps for girls to try science, technology, engineering, and math through fun experiments and solving real problems. We had a great time listening to Mythbuster’s Kari Byron talk about her journey to science ed TV from sculptor to tester of myths. One especially grabbing tale was a test for the smell of fear in a glass coffin trapped with a mass amount of crawling scorpions.

One story of hers that stuck with me was how she got her start with special effects work in the M5 studio, owned by Jamie Hyneman. A friend encouraged her to go see what special effects were all about, thinking there was more money in movie-making artisan work than other starving artist outlets. She was so inspired she went back to put together a portfolio and told him she’d work for free so she could learn as much as possible about making effects and movie props. Well as it turns out, Jamie’s a frugal guy, and definitely got returns on his not-too-much-investment!


In listening to her story I realized there’s a parallel to my journey to open source. I was interested in “how are wikis really working for technical documentation?” so I offered to work for free on one. Turns out, that volunteer effort launched me into the career I have now, working on a large open source documentation efforts for OpenStack, the open source cloud. I could identify with the need to be brave, creative, empowered, resilient, and all of those are offered to me while working on OpenStack and in open source. How about you, when have you volunteered for work just to learn as much as you could about the work?


Grace Hopper, here comes OpenStack

This is my first time going to the Grace Hopper Celebration of women in computing. I’ve never been to a conference where they take over men’s bathrooms to give women fewer lines! There are over 4500 people registered for the conference in Minneapolis. I’m so proud that Rackspace is a sponsor this year as it shows real dedication to adding more women at all levels of our organization. Niki Acosta has a great post on the Rackspace Blog talking about how great it is to be here. I know this past year has been a great one for me personally as a woman at Rackspace. Adding Diane Fleming as an API writer on OpenStack followed by Dana Bauer as a development community manager makes our team plain fun. And our fellow teammates like to remind others, “we’re not just gents you know.”

ghc2012-osdayOn Saturday OpenStack is participating in the open source day. OpenStack provides open source cloud computing software for computing, storage, and networking and is backed by a non-profit Foundation. Iccha Sethi came up with the idea that OpenStack should participate in Grace Hopper this way. We have been working on growing an inclusive and diverse contributor base for years now, because even very extroverted people get tired of talking to each other all the time. Actually, since OpenStack has an in-person Summit each six months to plan features going into the next release, we get to talk to each other quite a bit. And we want to hear from all sorts of different perspectives, it makes our software more interesting to work on. Plus we were all noticing the overwhelming number of guys at our Summits, so we’re working on outreach. And, we want to be good at onboarding and welcoming new contributors, so this workshop is a step in that direction too.

Our theme for the workshop at Grace Hopper is “Learn about OpenStack and the Open Cloud – connect, network, contribute,” but participants are welcome to branch out however they like.

To set up the workshop, I spun up 20 cloud servers on the Rackspace Cloud using an image with devstack already set up with a non-root user. I ran, then, and made an image of the instance in that state. At the workshop, we’ll hand out IP addresses and passwords for participants to use devstack for a commit. As a backup plan, I do have Virtualbox instructions using an Ubuntu 12.04 ISO and a devstack.ova file that Ryan Lane created for Lyz Krumbach Joseph and Anita Kuno’s use at a CodeChix workshop. Happily Lyz posted her write up and I was able to use a lot of their materials as a starting point. They also had 32-bit ISO and OVAs on the ready for laptops with 32-bit processors. All of these are on a USB stick, just in case we need them.

Based on our experience with a recent Rackspace hackathon, I set up an Etherpad for all the participants to access on the day of the event. All the instructions are there as well as on a handout. Please feel free to use these materials if you do any workshops of your own.

Reviewers, I hope you’ll be on the lookout for patches from newcomers. Newcomers, I hope you enjoy working on OpenStack as much as I do. Grace Hopper, here we come!

techpubs work

OpenStack DocImpact Flag Walk-through

In our unconference sessions at OpenStack Docs Boot Camp, we talked about integration with development, the DocImpact flag, and I came up with these guidelines for what a DocImpact commit message should contain. I wanted to talk about it here on my blog before posting to the wiki to see if I’m missing anything crucial.

  • Who would use the feature?
  • Why use the feature?
  • What is the exact usage for the feature? For a CLI call, provide examples of all the parameters the patch includes.
  • Does the feature also have permissions/policies attached?
  • If it is a configuration option, which flag grouping should it go into? (Defaults and a description are already required by their gate test on nova.)

I’ll walk through it with a DocImpact bug I worked on today titled “havana: nova Add force_nodes to scheduler hints“. I went on IRC to ask the developer the questions and got these answers:

  • Who would use the feature? Only administrators using the baremetal driver for nova.
  • Why use the feature? Baremetal is used when doing high-performance computing or standing up clouds from baremetal. Turns out, this driver is getting moved out of nova soon, and spans the realm of Heat + TripleO, and still a work in progress, but getting really close. HP is using it already to get compute nodes ready for action. This specific feature is used to specify exactly which node to send the next set of commands to.
  • What is the exact usage for the feature? For a CLI call, provide examples of all the parameters the patch includes. It’s a call on the nova boot command with the –availability_zone flag, and you can have nova boot –availability_zone=zone:host,node. You have to get the node in the form of a UUID.
  • Does the feature also have permissions/policies attached? In this case, it turns out some API features didn’t land in Havana, and so if you have to use a UUID for a baremetal node, then you have to do a SQL database call in order to get the UUID. This usage requiring database access is sort of “ugly” so I’m still trying to decide what to do with it. Also, I recall a lot of discussion around scheduler hints passed in with the –availability_zone flag so I’m still working on this doc bug. It would help greatly if the developer had done some of this end-user thinking up front, but he couldn’t have known back in May that the API changes wouldn’t land in September.
  • If it is a configuration option, which flag grouping should it go into? (Defaults and a description are already required by their gate test on nova.) For the baremetal driver, we already have docs for the configuration reference, but it was a good check to do. I found that the wiki page had a redirect to a simpler page name, so I’ve included that in my patch.
work writing

OpenStack Docs Boot Camp Wrap Up

We didn’t have to do pushups to get the wifi password, though I did consider that requirement for our boot camp theme and decided, no calisthenics required. We gathered about 20 writers and developers who wanted to learn about OpenStack documentation in the Mirantis training room for two days this week in Mountain View, California.

The idea for a docs boot camp came from the OpenStack Infrastructure team who held one back in June. We wanted to enable more people to contribute to OpenStack documentation through in-person training and team building. It’s not like a book sprint, with the goal of a book in five days, but rather a training session, with questions and answers in real time.

We even had a schedule! And presenters! With labs! We also held an unconference each day in the afternoon. As presentations sparked ideas for further discussion, we wrote them down on notes and everyone could vote on which ones to discuss further during unconference time.

Day one I gave an overview of OpenStack Documentation to give people the history and more context for how we follow development processes.

Jim Blair from the infrastructure team gave an overview of how doc builds work and how we can make templates for our doc build jobs. Since the openstack-manuals repo recently went through a restructure for simplicity (Sunday we were still merging!), this was very timely information. We ran through a lab to make a Jenkins job with a yaml file and also talked about our gating jobs and how to improve them to give better results in the content.

David Cramer, our Maven clouddocs-tools plugin maintainer, did a presentation about DocBook and the newly added support for
, a mechanism that allows for easier link management.

After lunch and a walk to a local park on the other side of a satellite Google office, we switched the schedule a bit to have Nick Chase tell us how to contribute to OpenStack documentation — by showing the onboarding process and how to commit a patch to openstack-manuals. We also had an unconference session about how to get new writers hired at different companies going with good projects.

Basically, read the OpenStack docs! Report doc bugs! Triage some doc bugs!  Edit based on our conventions and standards including proper spelling! Fix those pesky doc bugs! Get paid! Win!


Monday evening we enjoyed boating and dinner at Shoreline. Ahh. I also followed a Google self-driving car onto the Google and LinkedIn campuses! Fun.


Tuesday morning we were back at it, and I finally remembered to go around the room for introductions. We had doc-loving representatives and training enthusiasts from Cisco, HP, Mirantis, Nexus IS, OpenStack Foundation, Rackspace, RedHat, SwiftStack, and Yahoo!

Our next technical topic was a talk about API documentation with WADLs with Diane Fleming. I still marvel at the great output we can get from WADL, and especially appreciate how much work it takes to maintain accurate request and response samples. Diane has fixed literally over 100 doc bugs since she started working on OpenStack docs last year. She’s an amazing doc contributor.

Next we got all geeky about doc tools again with a presentation and demo of Publican from RedHat writer Stephen Gordon. I asked a ton of questions about their authoring processes, such as “do your writers write differently since they write “articles” instead of book “chapters?” Fascinating look into the world of all-open all the time. They are making the upstream OpenStack docs even better so their own customers get better docs.

Before lunch, Tom Fifield gave a presentation about the autodoc tool that is now working great for scraping the configuration options and putting them into the OpenStack documentation. It’s really amazing, we’re able to document over 1500 configuration options and keep up with code like never before. It’s still a manual, human-must-read process to make sure our groupings for configuration options are correct, but this autodoc tool is a really cool tool that we can keep iterating on.

After lunch, Shaun McCance talked about his plans for consolidating the Install Guides into a set of “choose your own adventure” style books. Michael Still and I had to attend the Technical Committee meeting so I had to miss out. The adventures are in an Etherpad and Shaun has six weeks to get this adventure done! Go go Shaun.

I think we all had a good time together, finding like-minded docs people, creating relationships with training-minded people, and solving some docs problems all in real-time. Thanks so much to Mirantis for hosting and feeding us so well, much appreciation to Rackspace for sending us and giving us such a fun adventure Monday and delicious Dish Dash Tuesday, and great gratitude to the OpenStack Foundation for supporting two travel grants and supporting fine folks like Tom Fifield, Stefano Maffulli, and Jim Blair. We can go forth and rock more docs!

techpubs work writing

Discipline and Diplomacy: Docs in the Open

In open source, all sorts of interesting connections happen. In open source documentation, an even more narrowly defined group of folks connect the dots for others. Recently I was interviewed by Mirantis, an OpenStack services startup, about my involvement with OpenStack documentation. They’re doing a series of interviews with the technical leads in OpenStack. We had a good time talking, and here’s an excerpt with a link to the full interview. I wanted to share it for my readers to see my open source views as a snapshot.

Mirantis: Can you please introduce yourself?

Anne Gentle: I work on OpenStack documentation full time at Rackspace, and I actually was the second hire Rackspace did for the OpenStack project. It was the greatest match I could ever wish for. I wrote a book in 2009 about how to do community collaborative documentation, and I had volunteered a lot with open source docs projects. This job showed up in my backyard in Austin, Texas, and I just jumped at it.

Q: What is the major difference between open source and closed source documentation?

A: The first big difference is interest in open-ness everywhere, from authoring to publishing to display. I was even asked if all of our fonts are open source in the first few weeks I started! Our toolchain is open to anyone to author with or tinker and re-use themselves. The second difference is in licensing. In a closed source environment, the documentation is very legally bound to provide a certain service-level or billing agreement. The idea behind open collaborative docs is that anyone can edit them and, in some communities, the ethos is very involved in the attribution of content. That’s a really good case for creative commons licenses.

So there’s a whole range, but a lot of it is around licensing and the freedom of the content, I also believe there’s a lot of interesting innovation going on in open source. For many of the same reasons you would do open source coding, I think there’s a similar draw for open source docs.

Q: What makes open source documentation so special?

A: There is a need to have a lot of discipline around documentation, and open source surprisingly lends itself to that. Open source, especially projects that try to tie docs to code as much as possible, are actually going to be very disciplined in their processes. Read more…

work writing

Openstack – The Terrible Threes?

I don’t know about you, but for my kids we suffered the terrible threes much more than any terrible twos. This week OpenStack, the open source cloud, turns three years old! Booyah!

Happy 3rd Birthday, OpenStack

From where I sit, I can envision some boundary testing as we define OpenStack for certain. And possibly OpenStack will ask “Why?” constantly? I think back fondly to the awesome toddler line of questioning, “But why?”

With my kids I invoked “house rules” quite often. House rule: no DSes or screens at the table. House rule: inside voices indoors and in the car. House rule: you can only point a squirt gun at a person with a swimsuit on. OpenStack has great house rules in our four values around open. These are house rules that I’ve felt we’ve embodied since the very beginning.

For the first birthday, I made this Lego still video for fun. I’m looking forward to more celebrations and I’ll be at the one in Austin this Thursday.

We automate all the things, while still making sure the people in the community get their say, get their code on, and keep working together.