The OpenStack Blog

Author Archive

Bring on the Crazy: Zero to Book in Five Days

Well, since my team mate Everett has outed me as crazy (yes, it’s true), I think I’ve got some ‘splaining to do! It’s true, we’re crazy, but we’ve got to write that operator’s guide — for operators by operators. And if you know ops folks like I do, you realize quickly that these guys have hardly any time to write down their notes! We’re going to pluck them from their day jobs, fuel them with coffee, BBQ, and TexMex, and get to writing.

I’ve run doc sprints for OpenStack at various times on different scales, but this one is highly focused. So highly focused in fact that I’ve turned down people who wanted to attend but hadn’t run clouds day-to-day. Sorry guys! Super hyper focus, blinders on.

I had originally put the proposal together for the Google Summer of Code Doc Summit, which I attended in 2011, but out of 30+ applying organizations, we weren’t selected. Undaunted, I revised the proposal for the OpenStack Foundation to consider, and they are funding it!
We’re gathering in the Willie Nelson room at the Austin Rackspace office next week, and we’re going to try a tool called BookType, hosted by Source Fabric. It’s the same tool I’ve worked with for book sprints with FLOSS Manuals, and it’s made specifically for sprinting. We’re using a pre-installed instance of it at If you look at it today, it’s empty except for a Test book sandbox. By next week it’ll be bursting with content! The outline we’re working with to start is at Thanks to everyone who has reviewed it and commented so far.

You all are welcome to watch our progress next week at at and offer editing and reviewing as we go. Please realize it’s a pressure cooker of a week, and a real challenge. I’m saying, be helpful and encouraging so we can be productive and accurate. Once we’re done, ship it! We’ll have copies of the book available (likely for a donation initially to cover costs) by the end of next week.

If you want to hear all the gory details, we have a few opportunities. Next week, if you’re in Austin, come see us at the Austin OpenStack Meetup on Wednesday night. Then, at the Summit, we want to bare our souls at a panel titled, On Writing the OpenStack Operations Manual in 5 Days. Come see if we are crazy, or driven there this week.

Let’s Get this Started!

I went to college in Indianapolis as one of the fine Butler Bulldogs. Each spring the Indy 500 car race is a celebrated event. On Labor Day weekend, the call for the engines to start is made by stating “Gentlemen, start your engines!” When female drivers are competing, the call becomes “Lady and Gentlemen…” or “Ladies and Gentlemen, start your engines!” I’m pleased to say that we’ve added a few more ladies to the OpenStack contributors starting line this month. In December we got to know each other through a Google Hangout, here we are waving and smiling for the camera.

The Outreach Program for Women is coordinated by GNOME and OpenStack is one of ten participating organizations. The OpenStack Foundation, Rackspace, and RedHat sponsored three interns, and after our careful selection process, we chose these three fine candidates and matched them with the mentors listed below:
Laura Alves da Quinta (, Buenos Aires, Argentina – Documentation – Anne Gentle
Anita Kuno (, Haliburton, Ontario, Canada – Python Clients – Iccha Sethi
Victoria Martínez de la Cruz (, Bahía Blanca, Argentina – Horizon’s Workflows – Julie Pichon

We are seeking sponsorships to bring all of them to the OpenStack Summit in Portland in April. If you are interested please contact Anne Gentle at [email protected] For a few thousand dollars, we can learn from them as much as they are learning from us. A great opportunity for some great interns!

Welcome New Outreach Program for Women Interns

Ever notice that sliced pineapple looks a bit like a yellow OpenStack logo? Since pineapple is a symbol of hospitality, I think we’ve foreshadowed how welcoming our community is.

With a flurry of applications, we had a difficult decision in front of us, deciding who would be our newest mentored contributors through the GNOME Outreach Program for Women. All the applicants were enthusiastic and personable, knowledgeable and technical. I’m pleased to announce that the decisions have been made and these three are going to work on OpenStack full-time from January to March:

Updated to add: The OpenStack Foundation, Rackspace, and Red Hat sponsored one internship each, and I want to be sure to express our appreciation to our sponsors. Thank you.

Our interns are expected to blog about their experiences, and we hope to get sponsorships for them to travel to the next Summit to share their projects as well. While they’re here to learn from us, I think we can all learn from them and their fresh perspective. Welcome Laura, Anita, and Victoria!

Starter docs and articles

I wanted to send a note out to discuss the growth of all the starter docs and “articles” on a particular topic. Thanks all who are sending these as links to the mailing list or tweeting ‘em. We are listening.

The doc team has been discussing ways to ensure we help people find what they seek while still getting high-quality content into the “official” documentation. Here are some ideas. I’d like to get input from our wider community as well.

What we’re doing:

  • Add a “Where do I start?” section to the docs landing page. Let us know what you think of this approach by taking a look at the pending review. We discussed quite a bit a more friendly approach to the docs site but I haven’t identified a web dev and designer to do the re-do, contact me if you’re interested.
  • Reach out to writers and where licensing allows and something “official” is not already documented, bring the content into the official docs. We’ve done this a few times now, an example is how to custom brand the OpenStack Dashboard.
  • Add link to helpful blog entries to a “BloggersTips” wiki page.
  • Expand the install/deploy guide to include more distros so the “single distro” guides can standalone. This effort is still a work in progress.
  • Hastexo has offered to write a separate high availability (HA) guide, so we won’t bring in their 12.04 “all in one” install guide after all, since the CSS OSS Starter Guide covers a similar scenario.
  • Remove “articles” from RST docs. (Currently nova only, in further discussion with the Project Technical Leads, QA and CI team leads.)
  • Add blog URLs to the Google Custom Search Engine at I took this as an action item from our last doc team meeting.

What we’ve discussed:

  • Removing redundant docs. At the Design Summit, members of the nova core team asked for removal of “article” style RST documents from the nova source repo, creating a more doc-string based Members of the swift core team, when asked, did not want to go to this architecture. I haven’t specifically asked all the PTLs on this particular item. So there’s still a potential problem here of consistency, where to write what, and having all the sites that aren’t really tied together. I don’t have a good solution to suggest just yet but know we’re thinking about this particular problem. One idea was to have devs who want to write compose WordPress “articles” and that would aggregate together, but we haven’t found an ideal implementation (design is fine, working code, not so much).
  • Setting up a separate WordPress blog for documentation only. Apparently the aggregation tools just don’t give us all the requirements for version labels, bringing in one blog entry at a time (RSS feeds are needed), and so on.
  • Setting up a “support knowledge base” article site such as We discussed this at the last doc team meeting. It seems to solve a lot of problems we have, but my current thinking (which of course can change) is that a support KB is for troubleshooting articles, while the “official” docs should create a happy path. These are two different scenarios, and I’m pretty sure the docs team cannot take on the support scenario with our current resources. A support knowledge base with translation built-in will go a long way in supporting our growing base, so this is important to me, but not in the Folsom plans currently.

I’ll follow up with each PTL for the docstring discussion, and welcome all input. Thanks for reading this far, and thanks for the docs. Now get started!

Starting line

OpenStack Talk hosted by the Computer Society of India Pune Chapter

This is a guest post from Devdatta Kulkarni. Thanks Dev for sharing!

The Computer Society of India (CSI) Pune chapter organized an OpenStack talk with me, Racker Devdatta Kulkarni, on Saturday January 21, 2012 from 5.00 pm – 6.30 pm.

Sunset in Pune by flickr:yogendra174Approximately 35 people attended. The audience primarily consisted of people with a technical background. Technology professionals were the most represented category followed by college students, followed by researchers.

I divided my talk into two parts. In the first part, I touched upon the need for OpenStack, the project’s history and mission, and the current projects. In the second part I delved deeper into design and architectures of Nova, Swift, Glance, and Keystone, and concluded with information about how to participate in the community.

At the end of the talk I did a quick show of hands to find out how many attendees knew about OpenStack prior to the talk. Given that I saw only three hands in response, I think the talk certainly helped in raising the awareness of OpenStack within the technical community in Pune.

Here are some of the questions that came up at the talk. Anne Gentle wrote the answers for the questions and I want to share with the attendees as well as OpenStack blog readers.
Question 1) Performance benchmarks of OpenStack deployments. They have experimented with deployment of about 200 VMs and were seeing average VM creation time of about 20 minutes. They wanted to know if this was something expected. Also, they were wondering if there are any OpenStack performance benchmark results that can be shared with the community.
Anne: A 20 minute wait sounds like a long time to me for a single VM but a short time for 200 Vms. We haven’t found a good way to share performance benchmarks yet but a post to the mailing list would probably elicit responses. I’ve also seen John Dickinson talk to folks on IRC about their Object Storage benchmarks.

Question 2) Guidelines on topology. They wanted to know if there are any published guidelines regarding the optimal topology, such as number of glance servers, number of compute, volume, and network nodes in Nova deployments?
Anne: I’d recommend they take a look at for both physical and logical architecture diagrams that show the number of servers and how to scale out a deployment.

Question 3) Active Directory support in Keystone. Is this being discussed within the Keystone working group?
Anne: It’s often discussed but no one has stepped up to write an AD plugin for Keystone yet that I know of.

Question 4) Is there a QEMU-based development environment for OpenStack?
Anne: Try out and if you run it in a VM, it’ll use QEMU.

Question 5) Can you give pointers to learning material?
Anne: Each of the projects has a development docs site (,,, and so on). You’ll find API and admin docs at

Hacking on Ebooks

Gentlemen prefer PDF, according to Tim O’Reilly’s data from Rough Cuts five years ago. At OpenStack we see some preference for PDF, though there are three times as many visits to the HTML version of our Compute Admin manual. Still, the PDF version of the guide is downloaded about five times a day. I do believe that gentlemen prefer PDF or some sort of book-like reading material. When asked, readers cite portability and search scope as two benefits to the form. However, as David Cramer, our doc tools developer put it at our recent hackathon, “PDFs are like cement.” With the boom of mobile and tablet screens, a stretchy and flexible screen-reader format like epub fills a need – we need content that works well on the 200 plus devices that fit into one hand.

So on 11/11/11, in the Austin Rackspace office, we did some hacking to be able to create epub output from our DocBook source files. I blogged about it for the OpenStack Planet blog from my blog, DocBook, ePub, Hackathon, what more could you ask for? prior to the event, talking about some of our prep work.

I’m pleased to show you the results – we did get output for epub and also tested the Mobi output on a Kindle, all in one day, with a team of about seven hackers including developers, writers, and testers.

We first tested the process using built-in epub transforms that ship with Oxygen, our XML editor, who supports open source projects like OpenStack by donating licenses to documentation contributors. Thank you Oxygen! We were able to use that output to start testing. Here’s our white board with the list of bugs.

While the writers and testers were hacking on output, programmers were working on ensuring we could get the epub output through Apache Maven, our build tool. By the end of the day, we could output epub through our automatic build process also!

As happens with hackathons, there’s some cleanup work to do – for example, our neat-o dynamic SVG cover page that takes in variables like the book title doesn’t output a cover for the epub. Also, most “real” epub output workflows convert tables from text to image (I know, crazy huh, when you think about the loss of search capability), but the tables in epub output act a little funky when resizing. Also, mobi, the Kindle format, has a problem with the way lists are marked up, but these are fixable and on the bug log.

I haven’t decided yet whether the epub output is high quality enough to offer it for download for every book on the OpenStack docs site, nor do I know if there’s much demand for the output, but I’d like to offer the OpenStack Starter Guide as an epub download. The team at CSS OSS works hard on this content, and I’d like to see it get spread onto many devices. Let me know how well it works for you and if you think epub has a place as a regular output for OpenStack documentation.

Happy Ada Lovelace Day

Ada Lovelace day, October 7th, is a day for bloggers to write a story about an inspirational influence in their life in technology.

For me, there were two influential woman in my life as an undergraduate chemistry student in the early 90s at Butler University in Indianapolis, Indiana. One was my first college chemistry professor, Anne McCowan, and the other was Butler’s scientific librarian, Mrs. Howes. Both influenced me through words, and bringing the importance of words to my attention. Professor McCowan stated on the first day of class:

“Chemistry is a study of nomenclature. Once you understand the naming and vocabulary, the world of chemistry is opened to you.”

It was such a simplification of an intimidating subject that it crystallized the learning process for me. If I studied the vocabulary, the rest would follow. And here I am, combining the wonder of worlds and technology every day.

So on today, Ada Lovelace day, I want to ask, how can OpenStack be a welcoming community for women in technology? I have ideas and want to share them with the community. These are both small ideas and large ideas.

  • Inspire girls when they’re young. I have volunteered with an organization called GirlStart here in Austin, Texas, and I think they’ve got the right idea, influence girls to enter technology in middle school and elementary and encourage them to go to college. A few years ago I went to lunch once a month with middle school girls where we talked about simple ideas such as “what does it mean to be smart?” That group of girls will be in high school now, and I hope they find technology a good path for them.
  • Invite women specifically. I spoke with Noirin Plunkett at OSCon this summer, and she said that women don’t necessarily have the confidence (or is it ego) to understand they are being specifically invited to participate in a tech initiative or open source project. You can specifically say to a group of female collage students for example, by saying “our project needs you specifically, not just your male colleagues.”
  • Start in your neighborhood, at your company. Since Rackspace is a huge supporter and founder of OpenStack, we want to ensure that we bring our women to the project and make them feel like Stackers are their kind of people. Stackers are professional, mature, and respectful of each other. We certainly have heated discussions but all input is valuable. I want to start locally by inviting women to Austin Cloud User Group meetings, by recruiting women for Rackspace jobs, and putting myself out there constantly, which is not always comfortable but it is rewarding.

How about your perspective here? Where will you start and when? Let’s take these first steps towards inviting more women to join our open source cloud computing efforts.

Documentation Contributors Styling Ts

Why give your time and efforts to an online community? Researchers like Peter Kollock have identified and studied reasons for people to contribute to online communities. I try to keep the basic principles of online participation in mind for documentation contributors all the time, and find ways to recognize the people making a difference with the docs. The motivating reasons for contributing to technical doc or offering technical support in a community include:

1. Reciprocity – Help out others who will help you later or already did help you out.
2. Reputation – Build your reputation as an expert in a given area.
3. Efficiency – Write it down so you save time later, either your own time or others’ time.
4. Attachment – Feel like you’re part of a bigger mission and vision.

It’s within these motivating reasons to find a place where you belong that prompted me to send some t-shirts out last month. I also want to recognize their efforts here on the blog! Here is the CSS Corp Open Source Service Team sporting their OpenStack t-shirts in a team photo, led by Murthyraju Manthena (far left). This team contributed the OpenStack Compute Starter Guide, which quickly jumped to the top ten list in the web stats. They’re working hard on revisions for Diablo, and this manual was a great addition to the OpenStack technical library for the Cactus release.

CSS Corp OSS Team led by Murthyraju Manthena






There’s also the sense of reciprocity – giving back your info since you got Volumes working in your environment. Here’s Razique Mahroua sporting his shiny new ringer T as well, after re-vising the entire Volume Management section of the Compute Administration Manual.

Wearing your OpenStack t-shirt is a great way to show you are a Stacker. I realize that sending t-shirts to contributors can seem like a small token of appreciation for the sweat poured into docs, but I like to send them any way when I’m especially impressed with the dedication. These guys are also building a great reputation as OpenStack knowledge experts. They are also a huge reason why the number of doc contributors has jumped from six to nearly twenty in six months’ time!

OpenStack Documentation Blitz

I had a great idea come across my radar this week – a Documentation Blitz! I’ve been working on case studies for a second edition of my book, Conversation and Community: The Social Web for Documentation, and in one of the case studies from Sarah Maddox at Atlassian, I uncovered a gem of an idea. From Sarah:

We have also held a couple of documentation blitz tests. This is a very successful way of involving the development and support teams in testing the documentation just before the release date. The technical writers set up a plan, including a list of the documents to focus on and a couple of ways people can give us feedback. We usually include an IRC channel, as well as wiki pages and comments, so that the engineers can choose the way that suits them best. We allocate a time period, usually just an hour, and everyone dives into the documentation. The chat session goes wild, comments fly, and we end up with a lot of useful feedback.

I love this idea and want to experiment with it for OpenStack. Fortunately the timing is just right, with the Diablo release ready for a September 22nd release. So, here’s the plan.

On Monday September 19th, from 2:00-3:00 CST (Monday, September 19, 2011 at 17:00:00):

To get coverage on the other side of the globe, we’ll run the Doc Blitz for a second hour at 11:00 pm – 12:00 midnight CST (Tuesday, September 20, 2011 at 04:00:00).

Let’s go find some doc bugs!


Documentation Wrangling and Statistics Sharing

I’ve been tracking web analytics on the documentation site since we put it up in February, and I thought I’d share some of the more interesting nuggets of data I’ve mined. I believe the documentation statistics offer a crystal ball, a window showing the future of what’s up-and-coming for OpenStack. Let’s gaze together.

Flickr: pasukaru76

The site regularly tops 1,700 visits a day which is about 40,000 a month. Nearly 10% of visitors are site regulars, with 9-14 visits in a month, and new visitors account for over a third of the traffic. I find search and content analytics much more interesting than just site traffic, though.

At the top of the site is a custom search engine that searches the docs site, the wiki, and each developer doc sites (such as The engine is fine-tuned to only show results for the Cactus release documents in so that there aren’t a lot of duplicates with Yesterday I further expanded the custom search engine to include the documentation for projects in, namely Keystone, the Identity Service for OpenStack. As a result, you can more easily find Keystone API documentation and Keystone developer documentation. Hopefully it means those of you tweeting that you can’t find the Keystone docs while you’re out shopping with your family can now find them no matter your mobile circumstances!

Last month, the top search term for the site was Quantum, which revealed the need for our newly incubated project Quantum to add more documentation. Fortunately Dan Wendlandt is on the case and working on developer and administrator documentation now. Also, the custom search engine gives results on the OpenStack wiki for Quantum.

We also have a rather fancy implementation of custom Event Tracking so I can track search data when a reader searches within a particular manual. We have data starting with mid-June. Popular searches once someone’s within a manual are glance, dashboard, vlan, floating, and zone. Interestingly, terms like accounting and billing show up in both the individual guides search and on the main search. I can extrapolate a couple of items from this type of data:

  1. People recognize project names, and the Image Service (glance) docs are embedded within the Compute book for the Cactus release. For Diablo, the Image Service will have its own set of books.
  2. The Dashboard had been trending for a while, so I put the docs in the Compute books prior to its incubation. That looks to be a good decision still.
  3. Accounting or billing solutions don’t exist in the OpenStack ecosystem yet, but people are certainly searching for them.

Our custom event tracking tells us that we’re also getting about 100 comments a month using the Disqus tool, and users are answering other users, which is excellent, keep it up!

One additional tracking item that I find interesting is that downloading the PDF of the OpenStack Compute Admin Manual is in the top 10 exit pages. I think people get in, download what they need, and get out. PDF output is considerably more popular than I had realized. I guess a lot of people hop on a plane and read docs or want the manual at their bedside table to go to sleep with?

Hopefully this tracking doesn’t creep you out, because the data really can help me shape the future for OpenStack documentation. You can always opt out of these tracking devices, and I’m sure some of you do. Let me know if there are any other documentation insights you would like to know.

Back to top