I’m well past the three year mark, working on a new open source project that grows and grows every six months. I’ve been working closely with Diane Fleming at Rackspace to focus completely on upstream OpenStack. Upstream means that all of our documentation work goes to the open source project itself. So while Rackspace runs OpenStack in production and for our customers private clouds, Diane and I focus on documentation that helps any organization run and use OpenStack. We have put together an outline of what we do to make upstream OpenStack documentation better all the time.
Growth, scaling, and related challenges
When I started, there were just two projects with two APIs. Now we have 130 git repositories fostered by over twenty related programs. As you can imagine this scenario causes scaling difficulties but we are bravely making our way. Here are some of the challenges we have faced and what we’ve done to lessen the pain of coordinated, collaborative technical documentation in an open source community.
In the face of language and technical barriers, the OpenStack docs team used a combination of IRC meetings, documentation boot camp, Google hang-outs, a busy docs-team mailing list, and other methods to create a flourishing, global team of writers and technical contributors who have immensely improved the OpenStack docs in the last couple of years. The release that went out in Spring of 2013, three people wrote half of the docs. For the release that went out in Fall of 2013, seven people wrote half the docs. I can’t wait to see what our numbers are for the release going out next, on April 17th.
Team-building tools – the good, the bad, and the ugly
Here are some benefits and pitfalls of these tools:
- IRC: Pros – clear agenda, follow-through week-to-week, global participation now that we have APAC and North American meetings. IRC meeting bogs enable an automated log of minutes. Cons: difficult to find agreeable time, no face-to-face, hard to introduce new topics.
- Office hours: Seemed like a good idea but fell by the wayside, we did not have much attendance. As our team grows, people can stop by the IRC channel at any time to get one-on-one help.
- Google Hangouts: With the video and voice enabled, it is nice to see each other’s faces without having to travel. Hard to find an agreeable time with the round-the-world team.
- Boot camp: Extremely positive experience – spawned new ideas and new connections. Downside is the cost/time factor. We had great survey responses but decided we didn’t need one every six months.
- Mailing list: Good way to resolve immediate issues and gather consensus as well as multiple view points.
- Book sprints: Good way to get a needed book written and distributed. Not a good way to build ongoing community for maintenance, and in some ways you have to be careful not to build a book that no one else thinks they should contribute to. But community is just one part of good docs – this is a good complement to other efforts.
OpenStack docs – before and after
How have the docs changed due to team building?
- Cleaner, more compact library. We did a huge refactor prior to the Boot Camp, which has made it easier to specify what types of content goes where.
- Better writing. Professional technical writers have done an amazing job avoiding “frankendoc” — by editing, reviewing, and polishing with an agreed-upon style guide, we improve the actual writing to better serve readers and users.
- Better technical content. In OpenStack, teams have core reviewers and most teams require two core reviewers must approve a change before it gets built to the published site. As we expand our reviewers (not just core but many reviewers) our docs have improved technically.
- Better automation. By writing tools that scrape the code for docstrings we are able to keep up with fast-moving projects that release every six months.
- Timing with releases. We carefully scope what documents are considered tied to a release. The Install Guides and Configuration Reference are the only two books built from a set release. All other documents are continuously published.
OpenStack contributors – before and after
How have the relationships among contributors and contributors’ roles changed due to team building?
- Much greater communication among contributors – now we know each other on a more personal level, and feel more comfortable working together
- Contributors have found where their strengths lie in the community. Some people are more tools and gear heads and build gates and tests and build tools. Some people are natural editors and review heavily with suggested edits. Some people are blue-sky visionaries. Some people are heads-down system administrators and architects. There’s a place for everyone, not just writers.
What’s to come?
We want to discuss revisions to our original vision openly. This blog post is a starting point, but we are listening on all available channels. At the OpenStack Summit in Atlanta in May, I want to collaborate on a request for proposals for a new front-end design for our documentation that can help us make changes to how docs are authored. I’d like to find out more about ways to enable non-CLA contributors to the docs. I have lots of ideas and look forward to working with this amazing group to improve our processes and results.
