The OpenStack Blog

Author Archive

Dedicated Doc Day

Rather than having a doc sprint session at the upcoming Summit, I’ve decided to do a push for docs for Cactus with a single two dedicated doc days this Wednesday, April 6th, and Wednesday, April 13th. I’d like to get us all on the same page with this post. (Ha, page.)

I track my doc tasks with a bunch of Post-it notes on my white board, and I’ve moved a lot from In Progress to Done this release. But I want to have a day dedicated to OpenStack docs to keep adding supporting documentation to the project.

OpenStack doc task board


The priorities for Cactus were clearly on reference documentation for flags and the API for Compute, and for Object Storage, logging information. We’ve had great efforts here which are rolled into the openstack-manuals Launchpad project and automation surrounding flags is available in Nova.

I’ve published a draft for the Compute Admin Guide for Cactus and plan to place a new home page so that readers can peruse either Bexar or Cactus (trunk) documentation. For the dedicated doc day, the scope is narrowed to these topics:

Target Audience

As you well know, OpenStack provides documentation for developers and system administrators both. The RST-sourced documentation is for developers and the DocBook-sourced docs are for system and cloud administrators. This dedicated doc day invites writers for both audiences, with a focus on the topics above.


I’ll be in San Francisco at the headquarters-formerly-known-as-Anso HQ on Wednesday (update: 4/13). We don’t have room for additional writers right now, though, but contact me if you’re up for a group dinner that evening.

After a long day of writing and diagramming, we’ll need libations. I’ll post a place for a meetup in the Mission area of San Francisco once we determine a location.

Closing Haiku

And lastly, a haiku from Daniel Green, who wrote a Doc Sprint haiku for Atlassian and won their doc sprint haiku contest:

No time to eat now.
Should be writing more content.
Too late, never mind.

Latest Tips for Using OpenStack

We’ve seen a lot of development activity in the last couple of weeks for the OpenStack Compute project. It’s a flurry of activity, though no snow flurries appear on the horizon here in Texas. It’s tough to keep up with such an active development community, so I thought I’d write up a blog post with some highlights. Hopefully you won’t think these are early release notes, but there are enough changes afoot that I wanted to get a head start.

Shiny New Bytes for OpenStack Compute

Ah, OpenStack Compute, the land of the free software cloud and the home of the brave cloud pioneers. We’ve seen many improvements lately. The previous preview release of Compute (also known as Nova) had a config file for each service. The latest and greatest code base has consolidated all configuration information into a single nova.conf file. This consolidation makes configuration much simpler, and you don’t have to wonder which config file “won” in a head-to-head matchup.

The install script for developers that Vish Ishaya composed has been folded into the source code base itself in the contrib directory. I was able to walk through it myself, as narrated in this screencast.

We’ve also had a Racker, Wayne Walls, test and contribute an installation script for OpenStack that is available in the contrib directory as well. With it, you can install a cloud controller on Ubuntu 10.04 LTS with prompts for creating the configuration needed for the database, network, and so on, ready for production environments. I’ve walked through it and it is handy.

New Tricks for OpenStack Object Storage

For OpenStack Object Storage, a freshly-landed new feature removes limits on object size – you can retrieve objects larger than 5 GB now. On upload, you still upload in smaller-than-5 GB chunks, but the system “glues” them together to make larger objects for download. You can still use chunks if it makes more sense for your system, and download them in parallel if you don’t want to stream a ton of data in one chunk. This large object support is available in the trunk only, not as a package yet, so we’ll keep testing and cooking it in order to prepare it for the Bexar release in February. There’s a great story of how this feature came into being at The Story of an OpenStack Feature at Programmer Thoughts, John Dickinson’s blog.

Exciting times for OpenStack!

Doc Plans for Upcoming OpenStack Releases

I’m supposed to be strategic about documentation and well, I have to say I feel a bit behind in creating specs for documentation for the upcoming OpenStack releases. Much spec planning went on at the Summit, but I was so focused on the Doc Sprint that I didn’t set any concrete doc plans for Bexar and Cactus releases. I’d like to amend that and get input from everyone in the community and beyond. Here are some ideas that go into a single blueprint for documentation. I’d love to get feedback on these plans and specifications, which we can edit on the wiki.

1. Docs site – OpenStack needs a central site that curates the content from various other sources and gives a good user experience upon landing on it. My goal is to implement this in time for Bexar (February).

2. Official docs – OpenStack needs a way to indicate that a page or site as “official OpenStack documentation” meaning that it is as accurate as we can get it and the procedures have been tested. Again I’d mark this for Bexar.

3. Versioning documentation – We are taking small steps towards a frozen release page/site. For example, you should be able to go to and get a frozen-in-time site with the developer documentation from the 1.0 release. We can get this done in time for Bexar.

4. Man pages – We need man pages created for nova-manage, nova-compute, and nova-networking. The nova-manage man page is now in the builds but needs editing. It is sourced in doc/source/man from RST files and gets built with the Sphinx docs. This could be done for Bexar.

5. Tutorials – Now that we have virtual boxes and stack on a stick in progress, we need tutorials that are meaningful and simple enough to step through while still giving an impressive demonstration of the power of OpenStack clouds. Here are some ideas for tutorials:

  1. Create a LAMP stack for a web application like WordPress – demonstrate connectivity between virtual machines, describe how to scale as your blog gets super popular (hey, we can dream, right?)
  2. Build your own CDN to serve video content
  3. Academic calculations where you spin up 10 machines for a Mathematica project only for a day or so
  4. Create a news reader application using AMPQ/RabbitMQ

I think we could have one solid, tested tutorial done in time for Bexar with the remaining set for the Cactus release. Any thoughts on how to prioritize these tutorials? Which would be in highest demand?

6. Glance docs – With the Glance implementation still ongoing for Bexar, we need to plan for install and integration docs with the Bexar release.

Let me know your priorities for upcoming releases and we’ll update the specs for the encapsulating blueprint for docs work. The Docs site is the biggest item needing design and architecture, so I’d welcome input and ideas with a heavy weighting towards “Docs site!”

OpenStack Austin Release Award Winners

Rewards, high fives, kudos, and good old fashioned handshakes. We gave those out and more at our first public OpenStack Design Summit during a break from jamming on Rock Band Thursday night. Chief Architect Rick Clark and I (Content Stacker Anne Gentle) wanted to recognize members of the community who made a significant impact on the Austin release through a variety of contributions. Our community is in its early stages and going through growth spurts, and these members found ways to build OpenStack up during a busy release cycle.

So, please join us in congratulating these community members:

Developer Community Awards

  • Vish Ishaya – Vish was rewarded for submitting the biggest patch (9,000 lines or so) that also broke the most stuff. We like breakers as long as they can fix what they break.
  • Alex Polvi - We wanted to recognize all of Alex’s work building community ties and helping us realize the vision of open source for clouds by being a strong community builder.
  • Jay Pipes – Jay gets recognized for so much Karma in the Launchpad system that Rick is practically suspicious. Just kidding, he has answered questions, submitted patches, fixed bugs, and in general been a huge push behind support for OpenStack from a developer’s perspective.

Content Stacker Community Awards

  • Stephen Milton – He took the Swift all-in-one instructions and tested and created a multiple-server instruction set that Chuck Thier then edited based on the Rackspace Cloud Files experience. It was a great mini-sprint effort.
  • David Pravec - He is always helpful answering questions in IRC, plus he created outlines for three manuals for Nova – Administration, Deployment, and Cloud-Users. He also created polished diagrams that are worth 1,000 words. Each.
  • Anthony Young - We recognize Anthony and the Anso labs team effort to completely refresh the Nova developer documentation and docstrings. Look for the fruits of their labor at

We couldn’t build what we’ve built so far without all the combined efforts of all our developers, supporters, and documentation contributors. Take a minute to give these guys a high five with us.

And then get back to Rock Band.

Photo used with permission from Mark Interrante

Content Stacks

Yep, content does stack, and I wanted to describe some of the content stacks we have going now. It’s like pimp my ride, where’s the noun and where’s the verb?

Stacking Up

The OpenStack community has embraced technical content and the surrounding community is hungry for more. We’ve had great contributions from community members. A couple of highlights to me are the enthusiasm and friendly lines of questioning by David Pravec (alekibango on IRC), plus his outlines in Etherpad have been excellent starters for Nova manuals. He also feels passionately that we are creating manuals, not guides, providing exact information rather than just guidance. We also had Stephen Milton (grizzletooth on IRC) step up and take the Swift All In One page and test it on multiple servers, providing a brand new multi-server installation and deployment page that we’re still drafting. A student in Florida, Eric Dorman (Orman on IRC), who is studying security in the clouds, is writing security documentation for OpenStack. This turnout encourages me so much, thanks all.

We’ve got a Documentation page that stores the collection of pages we’ve started and outlines the plans for what pages need to be written. I really liked this blog post, Two months writing docs for Open Atrium and Managing News – lessons learned! and borrowed the outline ideas from there. It confirmed my thinking that there are a lot of expectations for technical documentation for completeness, and this outline, once it’s filled in, would bring a sense of “completeness” to the OpenStack documentation.

The and sites should be freshly outfitted with Google Analytics by the end of this week. We should have Google Analytics integrated in the wiki soon as well. This integration will give us ideas about which pages are often viewed, what searches bring people to the site, and the paths they take once they’re on the wiki for example.

One work area that has surprised me a bit is the use of Etherpad to write drafts and collaborate with a small group before putting the information on the wiki or in RST. We’ve coded Etherpad pages in RST so it’s a simple copy/paste to get the RST in the Sphinx build. I understand the feeling that writing drafts on the wiki feels like working on the document on the operating table with its guts hanging out. So having a more private collaborative area like Etherpad seems to bridge the gap between wiki page drafts and early, early drafts.

Doc Sprint

I’m shaping the agenda for the upcoming Doc Sprint the last two days of the OpenStack Design Summit. All times are Central Standard (GMT -6). Here’s how it’s looking:

Thursday Nov. 11

9:00-10:00 Attend Install Fest and install environment, update install
10:00-10:30 Training in either wiki or RST as needed, plan writing
11:00-12:00 Write
12:00-1:30 Lunch
1:30-2:00 Community Manager Stephen Spector to talk about documentation
2:00-4:00 Write
4:00 End of day check-in (IRC and/or con call)
6:00 Don’t forget the party is Thursday night, all doc contributors are
welcome! Buses will depart the Weston Centre lobby at 6:00.

Friday Nov. 12

9:00-12:00 Write
12:00 Mid-day check-in (IRC and/or con call)
12:00-1:30 Lunch
1:30-4:00 Write

The check-in at the end of the day enables us to connect with remote contributors, switch writing assignments, ask questions and so on. If you’re planning to participate remotely, please let me know so I can accommodate your needs. We’ll be on the #openstack IRC channel all day, and we can use a conference call or Skype if you’d like to listen in on Spector’s talk.

Official Content Stack

One of the goals for this quarter is to find a way to distinguish “official” documentation from “ongoing, in testing” documentation. Whether it’s a badge on a page or a whole new URL such as, I’d love your thoughts on how to indicate when a doc is tested, vetted, and official. I have ideas and examples but the community opinion matters and has weight in the decision, so please offer your ideas. You can email me at anne at openstack dot org, find me on IRC as annegentle, or find me on Twitter @annegentle.

Content Stacker, Reporting for Duty

Well, hi there. Glad you could make it. Let me introduce myself. I’m Anne Gentle, the newest addition to the hardworking OpenStack team. And I’m so eager to get started I can barely contain myself. I’ve been in lurker mode for a few weeks and now it’s time to reveal my role – I’m the OpenStack Technical Writer.

How did I get here? I first started working in open source a few years ago, and I applied my technical communication skills gladly because there is often a gap in documentation and support in open source projects. I became a big supporter of FLOSS Manuals, where we write free manuals for free software. We work in a wiki and in Booki, a new collaborative authoring platform. We also employ a book sprint technique where we focus collaborative authoring efforts into week-long sprints. I’ve helped with a few book sprints and think it’s a great technique for open documentation.

Where do I go from here? Today I want to start outlining some documentation strategy to get your feedback and tweak it. We’ll be testing doc efforts as we go and likely start with the Object Storage area.

Audit and Analysis

This phase should answer questions like, what exists already and how is it doing? I plan to do a thorough content audit right away. Seems like there are a lot of places to write things down, and I want to determine what’s out there. I’ve started reading through the Swift documentation and learning about Sphinx. We’ve all been around technology long enough to know that tools are not the complete solution, that makers and crafters help the content go from adequate to exceptional.

I’ll also study other projects (I’ve been observing several different projects for a while now). I’d like to hear your preferences here as well – how do you get information from similar projects?

An audience analysis also comes in this phase – who needs the documentation and what tasks do they accomplish with it? I expect to be prioritizing both administrator documentation and developer documentation as well as introductory information for those on their initial approach to OpenStack.


  • Build a table on the wiki showing where content exists.
  • Look for reuse opportunities as well as unifying characteristics such as audience, level of difficulty, chunking, and organization of content.
  • Describe the typical readers and the tasks they need to accomplish.

Creation and Collaboration

After an analysis phase, where I will avoid analysis paralysis, I want to look at content structure – what types of information should be created and where can you find them? Information typing is a huge part of what makes my life easier and more organized as a writer. Jacob Kaplan-Moss wrote a great post about writing effective documentation detailingwhat to write. I completely agree that you can write any technical documentation with tutorials, topical guides, and reference guides. I believe this approach will help us write helpful, useful documentation. I would like to build in documentation as part of the ethos of the community, part of what we value.

At first glance, the types of documentation needed may be easily divided by reader – developer documentation (which could live in the Python code with Sphinx, in the specs in Launchpad, and in Etherpad when real-time collaboration is needed) and administrator documentation (which could live on the wiki, that’s yet to be determined). We always want to consider translation and local community support, because not speaking English as a first language shouldn’t deter you from contributing to the documentation.


  • Create a Launchpad for documentation for requests and tracking purposes.
  • Create a starter style guide for the OpenStack wiki.
  • Talk to interested parties about contributing.
  • Set up starter templates on the wiki.
  • Write and edit as much as possible.
  • Plan for doc sprints on specific topics to coincide with in-person events.


I think the documentation should help support users first and foremost. To me, pragmatic, viewable results come first, fancy-pants solutions are second. I think that philosophy works great at Rackspace and I’m pleased to see it’s a core value - Results first, substance over flash.

How about you? What do you think should be the goals of OpenStack technical documentation? Support? Adoption? Education? All of the above? Let us know.

What can you do to help with doc?

Please, introduce me to people who want good documentation and recognize good doc.  Introduce yourself or name others. Send me examples of sites that do it well. Write things down as you go, even if they are rough notes. Help us shape a doc strategy so it fits our community.

You can read more about me on my blog at, on Twitter @annegentle, and get in touch any number of ways – comment on my posts, talk to me on Twitter, email me at anne at openstack dot org.

I’ll be asking lots of questions as I get started, but these are my initial thoughts. Ready to start stacking!

Back to top