Tag Archives: sprint

techpubs tools work

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.

Embrace the “un”

Embrace the un article thumbnailAn article that Janet Swisher and I wrote for STC Intercom magazine about unconferences, BarCamps, and Book Sprints is available as a PDF file from the stc.org site if you are an STC member. I have permission to post it as well, so click the image for a free download of the PDF file.

Janet and I collaborated on the article by using Google Docs and sharing the editing between us.

Here is an excerpt:

Embracing the Un — When the Community Runs the Event

While Web 2.0 has many definitions, it is fair to say that Web 2.0 involves embracing user-created content and the communities that emerge around that content. One aspect of being a member of a Web 2.0-enabled online community is the real world meetings that can happen at professional conferences or even networking events in your same town or city. User groups or focus groups are one type of real-world meeting, with a single goal in mind.

Unconferences and barcamps are another type of real-world event where people with similar interests and goals can get together to share information. A third type of community event has just emerged and this article highlights aspects this new BookSprint model because of its relevance to technical writing. This article describes the authors’ experiences with participating in these types of events, and in particular the FLOSS Manuals Book Sprint for the One Laptop Per Child (OLPC) project, held in August 2008.

Read more