Monthly Archives: November 2010

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.

Great State of the Union for Tech Comm

You might think I immerse myself in a feed reader all day long to find just the right tidbits to share with others. In 2007 we got to see how Scoble reads over 600 feeds, and that image still sticks in my mind. Well, that and I saw him at Rackspace’s headquarters a few weeks back, but I digress.

But information collection with that method is not really how I work today, and I’m guessing Scoble has different techniques than those used three years ago. Sometimes I find myself only reading links through Twitter and ignoring my feed reader for months on end. My tech comm information comes through serendipity quite often. Even when I let go of any attempt to trap, categorize, store away, and manage my information intake, I still get fantastic information about technical communication. Here’s an excellent example.

The subject line said something like, “Have you ever had a persona review your book?” Intrigued, mostly by the subject, but also instantly recognizing who it was from, I clicked through to the presentation, titled “Developing Content as a Business Asset.”

Why is this snapshot in time so important to me? Because when I read that Adobe wants to know how important the TOC is (it depends), and that CHM files are still the preferred way that Microsoft wants you to deliver help for Windows applications (apparently only through hope and prayer will this change), I get discouraged. I think momentarily that the state of the union for tech comm is stuck. Stuck in the past, stuck with tools invented in the 80s, stuck with standards created in the 90s, and stuck with the same vague value definitions of a professional organization born from a merger with yet another professional association in the 50s with its current name from the 70s.

But then I get an email like this and read through a presentation like this and know we’ll get unstuck.

I was floored. It’s not often that I catch a glimpse of the perfect storm, but this presentation has it all. It won’t take guff from vendors, it doesn’t preach or try to boast, it truly analyzes where we stand today, on the verge of embracing content strategy and web content. It really resonates with me throughout, especially “finding content gems” and collaborating with experts throughout the company. Answering the question, “how is your group an asset?” tout the presentation is a fascinating way to explore the various facets of content creation, care, and management.

When I was a grad student in the 90s I was fortunate enough to get to a few conferences even if on a budget, and I got to see Cheri Lockett Zubak, and let me tell you, she has her finger on the pulse of this decade’s value proposition for technical communication.

I say to Cheri, pave the way! Your presentation accurately provides a “state of the union” snapshot for all of us. I love it.