I attended the Open Help Conference in lush, green, over-20-inches-of-rain Cincinnati over the weekend and learned so much. I wanted to share my observations in a longer format than the 140 characters I used sporadically during the conference.
First of all, if you want to read through the presentations, we’ve gathered them on the Open Help event page in Slideshare. My presentation was called Sprints and Stacks: Building a Documentation Community. I walked through my experiences ramping up open source documentation for the OpenStack project. I was pretty honest about my expectations going in and the reality that ensued, which you can read about in the notes.
My Giveaways
These points are all made in my talk, but I wanted to share them here as well. Here are some of the surprises I’ve had while working on OpenStack:
- Publishers want OpenStack content. I feel like I’m in a fight to be an acquisitions editor some days. Everyone wants an OpenStack book, or blog entries about OpenStack to publish on their site.
- Doc sprint timing must occur with specific releases. Originally I thought I’d just run sprints at the Design Summit twice a year. Now I see that sprints should probably occur just prior to releases.
- I once thought docs were a good entry point for new contributors. I now sense that it’s really difficult for new people to contribute to the docs, and I also believe that developers should write for developers.
- Doc contributors need access to people they can interview incessantly. Plus they need access to hardware, big time. Neither are easy to offer now for OpenStack. I recognize this shortfall, yet haven’t solved the problem completely.
- I am seriously shopping around the idea of holding an OpenStack tweet chat regularly. If you are interested in hosting a regular tweet chat, please let me know.
- I have been amazed at the quality of content about OpenStack coming from bloggers. I am happily contacting them and incorporating CC-licensed content.
My Takeaways
I felt like I was in such great company. Shaun McCance did a great job recruiting like-minded people who love to share, discuss, and have fun with documentation. We had half-and-half women and men in attendance, and lots of women presenters. This ratio is a big deal to me as I get deeper into open source. Gender balance in open source and technology in general is a difficult sometimes contentious topic, but we’re definitely onto something good with this group. One of my favorite tweets was this one:
‘The number of women in an IT organization is the same as the number of people named “Dave”‘ (quoting @Loquacities (Lana Brindley) #openhelp)
and another great one from @jenzed:
The discussions at #openhelp are much enriched by having participants who are not members of the open source choir.
We had less than thirty people in attendance, but these were “my people.”
XML versus wiki
I have to talk about the dichotomy between using a wiki for community-contributed documentation and using an XML plus version-control system for collaborative authoring. Both methods were well-represented by Red Hat and Mozilla.
One of Red Hat’s 60 technical writers, Lana Brindley, spoke about their awesome XML-based writing workflow in Open Source Documentation in Four Easy Steps (and one slightly more difficult one). They have dedicated editors, a style guide, an IRC channel dedicated to grammar, and a search engine specifically created for writers to find content to reuse, plus a topic-based doc platform that allows writers to put together doc builds, which they built themselves when they realized they didn’t want to build a component CMS. What she described was a very mature and high-quality, yet agile and flexible and open, documentation process. Red Hat rivals any of the large enterprise documentation projects I’ve seen and accomplishes everything an enterprise needs to, yet with open source tooling, standards in XML, and somewhat hacked-together tool chains. Their content is translated to 23 languages, a feat only also accomplished by such companies as Dell, IBM, and Microsoft. Their culture sounds amazing, working for the “good guys” with tales of writers and developers working together to build the needed tool chains. I learned a lot about Publican and translations, about when to keep tweaking and when to release something to the wild.
On the Mozilla side, Janet Swisher presented a talk titled, Engaging developers in Mozilla’s documentation. Their documentation process is tightly coupled with development practices including tracking doc requests in Bugzilla. Considering that they write completely on the wiki-based Mozilla Developer Network, and that they’ve perfected their workflow over years, it seemed like a perfect match. They are also running frequent doc sprints, on their third this year. Their easy-to-use doc tools paired with their high number of page views have created a perfect storm for recruiting contributors and their content. For example, Google’s writers have chosen to put their content that’s not just about Chrome but geared towards Chrome web development on MDN. This gathering sounds like a perfect combination, curation from the creation point. She also included the reasons why people don’t contribute. One, their site is so beautiful and engaging that people don’t see the Edit button (they don’t know it’s a wiki), two, they’ve got “yet another login” syndrome, and they don’t want to bother with setting up an account, or three, they’re too intimidated by the relative “fame” of the original author to change “the” documentation.
Lots of Work
During Dru’s talk about Starting an Open Source Certification Program, I tweeted the following and @Sheppy (Mozilla writer Eric Sheppard) agreed with me.
Great talk from BSD author and community manager Dru Lavigne about certification programs at #openhelp. Wow just wow, the amount of work.
We’re in the early investigation stages of certification on OpenStack and we have a long road ahead of us. From the number of surveys to psychometricians ( had to look that one up) to collaborative exam design, open source certification is a unique program to run. Exam delivery and Angoff sessions were new concepts to me. Exam delivery has been an ongoing, six-years-in-the-making, process for BSD. Six years gives you pause. These groups are serious about certification and it shows. Fortunately we’ve hired Belinda Lopez who can navigate these areas and knows how to engage the community.
On the second day, we discussed language and localization and I learned that I can export our DocBook files to po for translators to fit into their workflow quite readily. You do have to be strict about freezing the English version, most likely, or you’ll have widely out of sync documents. Since I have two types of source files already, both RST and DocBook, I’m not certain about freezing the English version just yet. Perhaps after some reference configurations are available and documented and I get more hypervisor docs, we can look into translations. Lots of respect in the room for the project managers of translation projects in open source.
We also had a great discussion about recruiting writers and the difficulty in choosing channels for communication – go where your people are, or branch out to lots of social media sites? We had one of the Mozilla writers who has now participated in two doc sprints say that he found out about the doc sprint by searching for free t-shirts on Twitter. So he was a shining example of finding recruits through lots of channels, not just on your classics for your project. To me, this shows you that social media and tech comm have a connection and outreach and community support are upward trends. Jennifer Zickerman’s talk, Coordinating Documentation and Support: Turning Complaints into Contributions, was outright inspirational. Thunderbird has 10 employees, 50 contributors, and over 10 million users. These numbers are mindboggling, yet they manage and thrive. I tweeted,
Seriously cool way to create a support community with Twitter – see the Army of Awesome at http://bit.ly/mRty7U #openhelp
I’m very impressed with Mozilla, an organization that’s willing to take the negativity in some tweets and turn it into altruistic goodness and pay-it-forward attitudes with the Army of Awesome. These cutting-edge techniques are what we all should look for in open source projects. They get the job done with what they have because they are driven to help.
I relish the work ahead, and I so pleased to have the opportunity to work on open source docs with OpenStack. We had a great time at Open Help, and Scott Nesbitt has a nice write-up and links to each presentation on his post, Looking back at the Open Help conference. We’re all hoping Shaun has the energy to put one together again next year!