OpenStack Doc Sprinting

What a week! I’m recovered and finally able to reflect on our recent OpenStack Design Summit.

As you may have seen on the OpenStack Blog, we gave out three documentation awards to those who made a difference in the latest OpenStack release, Austin, by contributing documentation either on Etherpad or by submitting images or writing RST files for Sphinx output. Contributions have been super and steady and I’m extremely grateful for everyone making doc a priority.

We planned for a day and a half for a doc sprint as part of the Design Summit. In reality, I found myself being approached throughout the Summit by people who are interested in contributing documentation, writing doc in RST, or even pulling printouts from briefcases. The entire week exceeded my expectations.

On the third day of the four-day Design Summit, several of us gathered at a table in front of a projector to work on the documentation. During the week, some of the Anso Labs guys found me in the lounge and we talked about their all-new nova.openstack.org site which rolled out last week. Excellent! I matched up the theme so the swift.openstack.org site now matches. We discussed RST-based doc as the “voice of authority” documentation for developers. Basically, we were all advocating for “wiki or Etherpad as drafting area” and “rst in the source code as authoritative voice about the project” but are open to input on that.

Citrix contributors Zhixue Wu, Armando Migliaccio, and Youcef Laribi contributed an OpenStack Network Overview that we incorporated into the nova.openstack.org site along with a lot of implementation details from Anso Labs. The Citrix group also authored Rabbit documentation and Swift installation documentation which we’re folding into the sites now (and the sprint goes on…). Disney manager Joe Heck documented the entire Nova database schema with diagrams now available on the wiki. Remotely, David Pravec created diagrams showing Nova installation architectures and method and messaging calls which we’re able to incorporate into the site. All of us tested the installation documentation, and Bryan Walker from Accenture added edits for the single-node install based on his experiences. Once they were tested, Anthony Young took the wiki documentation and marked it up as RST to incorporate into the nova developer doc site. I also worked with Jorge Williams from Rackspace about the Rackspace API docs which he maintains in docbook, and Jorge gave me the source files for the Cloud Files API developer guide which we can re-use and incorporate into the OpenStack documentation. We also had a huge collaboration session with Dustin Kirkland and others to create specs for Stack on a Stick, a Live ISO image so you can get Nova running instances painlessly. I also met with Nati Ueno from NTT, who made a working VirtualBox image that runs Nova and we uploaded it to Rackspace’s CDN. Basically these give you Nova in a virtual system so you can painlessly run command to try it out, risk-free.

I hope I haven’t missed anyone – my apologies if I did! I’m finally recovered from the effort and able to look in the rear view mirror and wow, what a sense of pride I have in the OpenStack community.

This sprint felt like a great collaborative effort and gave me a chance to get to know the stackers who want to build great docs for OpenStack. While we didn’t do much future planning, I think we certainly got to know one another and now can comfortably email and comment on each other’s docs – that’s a huge step for anyone writing docs for any project. So I really appreciate all the hard work and want to say thanks for “gellin” through the sprint.

One comment

  • November 24, 2010 - 1:40 am | Permalink

    Hallo Anne

    Congratulations, it sounds like a fantastic and productive doc sprint. Like you, I find that one of the biggest benefits of a doc sprint is the contacts you make. They provide the foundation for future work.

    Have a good rest now!

    Cheers, Sarah

  • Leave a Reply