What’s difficult about this data analysis at this time is that we still need to release the docs even while we plan for the next six months. What I really want to do is look at the past six months and all the amazing work and accomplishments we have seen. The growth has been great and the fantastic feat of the Operations Guide really topped off my year. But we are still lacking enough strong doc contributors to keep up with the pace of code growth.

First, let’s look at the OpenStack code analyzes. The last six months showed 517 contributors. For example, Object Storage grew their new contributors by over 35 people which is probably doubling the involvement. Our Infrastructure team continues to raise the bar for helping us slam in more and more bits as fast as our little cloud servers can slam them. Here’s Monty Taylor’s report:

OpenStack code patches

                        Essex   Folsom  Grizzly
Patches Uploaded        11036   17986   29308
Changes Created         5137    5990    12721
Changes Landed          4235    4978    10561
Avg patches per Change  2.6     3.6     2.7
Landing Percentage      82%     83%     83%

What I want to do here is provide similar data that shows the growth of the project relative to the docs. I’m using the openstack-gitdm project to run the numbers for the documentation repos. There are eight in total but I’m just going to look at the top two, openstack-manuals and api-site. The openstack-manuals repository holds the install, configuration, adminstration, high availability, and operations guide. The api-site repository holds the building blocks for the API reference page, the API Quick Start, and other API guides (but not the API specs).

Here’s a listing of all the OpenStack doc repositories:
openstack/openstack-manuals – for operators and deployers, docs.openstack.org
openstack/api-site – for API consumers, api.openstack.org
openstack/compute-api
openstack/image-api
openstack/object-api
openstack/netconn-api
openstack/volume-api
openstack/identity-api

These are the types of statistics I want to know about doc contributions.
Number of doc contributors: 79. This is a great value.
Number of new doc contributors: 27. I like this from a growth standpoint.
Number of doc contributions: 512. There were 435 doc changes within openstack-manuals during the grizzly release, and 429 during the folsom release. Compared to over 12,000 code changes I instinctively know this wasn’t enough doc update. While we do have a good base set of docs, they are getting a bit crufty and we want to address that in the Havana release.

Number of employers: 49 (up from 37 last release). This is a high number. The highest doc contributing employer is Rackspace during the Grizzly release.

So, what about quality? The most bugs fixed by a doc contributor is 45 (well over half) by Tom Fifieldt. Tom is a great doc bug triage expert and I don’t know what we’d do without him.

How about what’s the top docs being read? The most read books are the Ubuntu Install and Deploy and the API Quick Start followed closely by the Identity 2.0 API Spec (wow that surprised me).

Here’s the reported data from openstack-gitdm. Thanks to Daniel Stangel for helping me retrieve this data. One hidden contributor is Jon Proulx, who wrote lots of the Operations Guide. Everett Toews also contributed a lot to the Operations Guide but won’t show up here. This omission leads me to suspect there may be other “ghosts” writing OpenStack docs, but I think the main point is, the top three shown below are far ahead of the fourth, fifth, and sixth-highest doc contributors.

Processed 435 csets from 79 developers
49 employers found
A total of 87457 lines added, 26085 removed (delta 61372)

Developers with the most changesets
Tom Fifield                 99 (22.8%)
annegentle                  86 (19.8%)
Lorin Hochstein             46 (10.6%)
Emilien Macchi              17 (6.0%)
atul jha                    11 (2.5%)
Mate Lakat                  10 (2.3%)
Diane Fleming                9 (2.1%)
dcramer                      8 (1.8%)
Aaron Rosen                  8 (1.8%)
gongysh                      6 (1.4%)
Ed Kern                      6 (1.4%)
Eduardo Patrocinio           6 (1.4%)
Alvaro Lopez Garcia          5 (1.1%)
Kurt Martin                  4 (0.9%)
Dan Wendlandt                4 (0.9%)
Razique Mahroua              4 (0.9%)
Gary Kotton                  4 (0.9%)
Dolph Mathews                4 (0.9%)
Christophe Sauthier          3 (0.7%)
Covers 80.459770% of changesets

Developers with the most changed lines
daisy-ycguo               37578 (39.9%)
Diane Fleming             19381 (20.6%)
annegentle                7624 (8.1%)
Tom Fifield               3126 (3.3%)
Lorin Hochstein           2757 (2.9%)
John Griffith             2390 (2.5%)
gongysh                   2169 (2.3%)
zhangchao010              2036 (2.2%)
Mate Lakat                1927 (2.0%)
Emilien Macchi            1684 (1.8%)
Navneet Singh              970 (1.0%)
Alvaro Lopez Garcia        647 (0.7%)
Brian Rosmaita             580 (0.6%)
dcramer                    554 (0.6%)
Dan Wendlandt              472 (0.5%)
atul jha                   431 (0.5%)
EmilienM                   428 (0.5%)
Joe Topjian                411 (0.4%)
Eric Windisch              376 (0.4%)
Ed Kern                    341 (0.4%)

At the OpenStack Summit last week I started looking for data that will help us shape the scope for the documentation for the coming release. With the right scope, we can keep up with code. Right now the docs scope that DOES release with code is docs for Python developers only, at docs.openstack.org/developers. However it seems people want install docs more than anything around release time. We will release the docs next week, 4/30/13, and have basic install docs in review now. We’ll need to keep track of doc bugs once we release of course. What we want to do in addition to decreasing scope is to increase resources, so we are working with member companies to create and fill upstream OpenStack documentation positions at each member company. Other creative ideas are welcome of course. I find this creative resourcing fascinating and I’m not about to whine about keeping up. Rather, I want to keep rising to the challenge.

The page has a lot of Javascript and CSS, DocBook and XSLT, XML and JSON behind it, which enables a few cool features. One is the details button, which gives an expanded set of information after you click it. Another cool feature is the ability to display either XML or JSON examples for the request or response with a drop-down list, and you can choose which to show by default. I also like the in-page search, which is more powerful than just using the browser’s page search feature because it digs deeper into the descriptions, expands to show any hits on your keywords in required and optional parameters, and in the response and requests codes. It highlights the found terms after expanding. Another cool aspect of the page is that all the Compute API samples are tested against a gate using code in the nova repository. Tested samples have been added in meticulously by Laura Alves, an awesome doc intern, with additional thanks to Sean Dague and his cohorts poking nova developers during the last dev cycle to ensure we have test samples for all API calls.

I believe there’s a lot of value in a long listing of reference information for the OpenStack APIs, and I’m glad Joe Heck took the initiative to get a blueprint going for it. David Cramer, Joe Savak, and Thu Doan at Rackspace took the blueprint and made it a reality with the Maven plugin at clouddocs-maven-plugin. The original goal of the page was to provide an all-in-one listing of all the API calls you could make against OpenStack services. At the time there were 3 or 4 services. Now we could potentially have 9 services with both admin-level API calls and end-user API calls, not to mention the extensions across 3 or 4 of the 9 services. So we are revisiting the all-in-one design of the page. Another aspect of the page is that it’s the only place to get documentation for the Compute extensions right now and the only site with tested examples without spelunking the code itself.

So, how’s it made? The basic building blocks of the page are:

• WADL files – Web Application Description Language, a proposed Wc3 standard in XML used for describing REST APIs, read all about it in the specification at http://www.w3.org/Submission/wadl/. Here’s an example with the Image API 1.0 WADL.
• XML files – Sample requests and expected responses. For Compute, these are copied right from the repository and each code submission that has an API piece must contian templates that build the example. Here’s a sample file: userdata-post-req.xml.
• JSON files – Sample requests and expected responses. Here’s a sample file: userdata-post-req.json.
• DocBook file – DocBook is an established documentation XML standard. Here it’s used as overarching XML organizing file, you can see it at api-ref.xml.

With these building blocks assembled in the openstack/api-site repository, you must also have a pom.xml to make the Maven plugin build the resulting api-ref.html page. The pom.xml is called by a Jenkins job maintained in the openstack-infra/config repository in a .yaml file. To build it yourself locally, install Maven and then do:

git clone git://github.com/openstack/api-site.git
cd api-site/api-ref
mvn clean generate-sources

Wait a while (maybe even 15 minutes first run) for the build to get all the dependencies it needs, then when you see BUILD SUCCESS, open the api-ref.html file in the target/dockbkx/html/ directory and revel in all the features listed above. If you want to submit a change, use the Gerrit workflow all the OpenStack projects use.

The backlog of bugs for this page is maintained at http://bugs.launchpad.net/openstack-api-site. If you see a mistake or want to ask for a addition, feel free to log a bug there. Laura Alves, our GNOME Outreach Program for Women intern, did an excellent job this past three months maintaining the page. My fellow Racker Diane Fleming is currently doing doc bug triage and fixing for the page as well. Future plans include adding a navigation layer on top of the page so it’s not one long page, but lets you pick the API for the service you’re interested in. With the additional APIs and new versions, we definitely want to keep updating the design as the APIs themselves grow and mature. Feel free to join in the API fun.

And I’m quite glad that we have the TryStack Facebook group for people to ask questions specific to TryStack. As the OpenStack doc coordinator I’ve found the group to be very valuable in telling me what information they’re missing, where they get confused about usage, and so on.

I especially like the video linking I can do in Facebook comments. Here’s a link to a video I made introducing people to TryStack.

When you open the scroll, you can see all the commands available for the “nova” client, which is how you send commands to the OpenStack Compute API at the command line. Clever!

One theme that stuck out to me was “I wish I had been less arrogant.” So many people, women especially, can be put off by the attitudes displayed by an open source online chat room or mailing list. I know I’m happy to see more women’s names on the OpenStack mailing list, asking and answering questions. I’m also happy to note that the OpenStack community is polite, professional, and welcoming to all.

An essay that fascinated me was “27 Things I’m Happy I Didn’t Know” by Alexandra Leisse. Ignorance is bliss in many arenas, open source is no exception. Sometimes learning from mistakes is the best lesson.

I also loved the “Never on a Friday” section of Sally Khudairi‘s essay that leads with “Everyone is a marketer.” She launched a new homepage for W3C on a Friday then boarded a plane for Paris. She landed to a flood of messages about a particular tag choice. Fabulous story.

Dave Neary‘s essay about conference planning, “Getting People Together,” has a detailed section about budgets and funding plus content and parties. Valuable and practical, this essay should be required reading for both conference planners and attendees.

What did I write about? Documentation and My Former Self is the title, and in it I realize how many contradictions I’ve discovered on my journey. Often, adding more and more observations will bring a flip turn to my stance on a documentation strategy. Fascinating.

The Open Advice book in PDF format is downloadable for all and I’d encourage you to read it, enjoy it, learn from it, and share it. Then, join in an open source community with those lessons already learned.

“PDFs are like cement.”

or

“Gentlemen prefer PDF.”

Turns out both are true! See my recent OpenStack blog entry, Hacking on Ebooks, for more context and attributions for those statements.

We recently held a hackathon which I blogged about earlier to discuss the prep work for creating epub from DocBook XML source for the OpenStack and Rackspace manuals. We had a very successful day of hacking on 11/11/11. A team of about seven writers, testers, and developers worked all day to try to make epub files. And sure enough, we did it!

Our list of bugs matches up with what others have noted about difficulties making ebooks, such as sizing images properly and enabling tables that scale when zooming in or out or being displayed on a small smartphone or a larger tablet screen. Turns out, many “pro” epub creators turn all the tables into images to avoid the sizing problem. We also noticed the problem with mobi output putting a new line for each list item, and I haven’t gotten the fix working yet. We’re starting with the OpenStack Starter Guide available as an epub download and automated outputting epub for that book. We’re checking out the downloads to see whether there’s interest and we’ll go from there!

Here’s a short introduction about making epubs from the FLOSS Manuals book, E-Book Enlightenment.

Of all the formats for e-books only EPUB combines small file sizes with the ability to do formatted text and illustrations. An EPUB is like a website contained in a Zip file, with a Table of Contents attached. It is also in one important way different from a website. A website is made with HTML (usually) but an EPUB is made with XHTML.

The difference is small but crucial. HTML is meant to be forgiving. If you make a web page you can leave out some tags, fail to close tags, or close tags in a different order than you opened them in. A web browser is supposed to forgive that, as much as possible. XHTML, on the other hand, is like HTML that is not forgiving. You can’t leave out a tag or put in a tag where the XHTML browser does not expect it. If an XHTML browser discovers an error in your page it can simply refuse to display it.

The end result is that an XHTML browser is easier to make than an HTML browser. A lot easier. It does put a burden on the e-book author to get his tags right, but in practice you’ll never create an XHTML file by hand.

With automation in mind, we’re going to use our existing toolchain to make the epub. Earlier this year, Robert Nagle, a tech writer in Houston, wrote up his findings about Docbook and epub. He writes for the Teleread website. What’s interesting to me is that he wrote up this blog post last year (11/7/10) about his findings while making epub from DocBook source and this past September said his next priority is moving his workflow to Oxygen + Ant + DocBook. David Cramer, our Doc Build Developer, has briefly tested the Maven-based toolchain by simply adding the goal generate-epub to a pom.xml file and building. That method did not copy over images. Then he tried building as part of the clouddocs plugin and received an error. We’ll start our debugging with the toolset, but we’ll also need debugging of our DocBook source as well.

Most of the “success” of the hack fest will be having fun and not sweating the small stuff. To me, we can call it done when we have epub examples for one OpenStack book and one Rackspace book that you can page through and read on a plane. Images should behave within reason, tables should be readable, and notes should be designated as such. Beyond those criteria, we’re exceeding expectations.

In case you’re curious about our tool chain for OpenStack docs, I have instructions on the OpenStack wiki. If you’re on a Mac or Linux machine, here are the quick steps for getting started with the tool chain for the openstack-manuals project:

1. First install the Apache Maven project.
With Macports already installed on a Mac, you can do this:

sudo port install maven2
or on Ubuntu

sudo apt-get install maven2

2. Install Git by referring to Mac or Linux instructions.

3. Get (git it? Ha!) and then build the docs with these commands:

git clone https://github.com/openstack/compute-api.git
cd compute-api/openstack-compute-api-1.1
mvn clean generate-sources

You will see a /target directory containing HTML and PDF output. Perhaps after Friday, you’ll also see epub output, who knows? While Friday’s Hackathon is for Austin Rackers, I’m happy to share our experiences here. Here’s hoping the OpenStack community will benefit from our hacking.

We had a few user stories at the Conference this year, and I was blown away when Tim Bell told the story of how physicists wake up each morning and ask questions about the basics of how the universe works. In the process of asking and answering basic questions the fundamental particles that make up our world, they collect 25 petabytes of data a year. And here’s the future part – they have a service level agreement that ensures their scientists can have access to the information for twenty years. And here’s the docs part of that – we’re tasked with maintaining API documentation that can enable the access to data and replication of a cloud computing platform that can process the data. If you don’t provide the magical incantations to retrieve and process your data, the service agreement is broken.

The presenter Tim Bell said he sometimes receives emails intended for Sir Tim Berners-Lee, the inventor of an information management system that enabled physicists to send information to each other, now known as the World Wide Web. He supports scientists who take pictures of what happens when tiny particles collide with each other at nearly two degrees above absolute zero. His was an inspiring and intimidating talk all at once. Updated to add: here is a link to his presentation on Slideshare, CERN User Story.

I have to admit, I believe using an XML standard like DocBook, which was invented in 1991, helps us future-proof the docs. Not that I’m over-confident either, it is quite intimidating to provide docs to the scientists of 2031. Perhaps even the college-graduation class of 2031, those future students who are toddlers today, will need to spin up virtual machines in order to replicate systems from 2011. With dedication, collaboration, and hard work, the docs.openstack.org site will be available. With the creation of an OpenStack Foundation, we look towards the long term, not the short, and plan to keep the docs ready for those who will need them in the future.

If you’re the type of person who is inspired by such documentation efforts, I’d encourage you to take a look at how the docs are made and collaborate with us. You now know how long-lasting your documentation efforts can be.

A page at a time is really tough for ongoing maintenance, when you don’t choose correctly the amount of information in a page. There are also difficulties with the rather immature technology in many wikis. Wikis were designed for simple editing, fast publishing. What if you have a sweeping name change? Anyone doing tech comm in a wiki knows that’s a headache for many wiki systems. What about a final spell check? Page at a time. How about search and replace? Page at a time. And let’s not talk about the times when you have to add an entire column to a table in an ASCII-based wikitext way. Your wrists will revolt, I assure you.

But an interesting expectation for a wiki that wasn’t considered when choosing the wiki is the need for comments on each page. Right now the only web systems for OpenStack that enable comments on a page are the OpenStack blog and the docs site. The docs.openstack.org site is built with DocBook XML with Disqus comments embedded on each page. It’s not quite perfect, as we’re learning as we go that not everyone wants to moderate every comment from every book on the site, and we’re still learning how to turn off hundreds of comments at a time, but it’s a great solution to a specific need. Yes, even the comment system selection needs an information architect analysis before you begin, but that’s the topic of a future post.

Ironically, our wiki doesn’t have a way to comment. So we just use it for project documentation and any comments on a project design are actually done in person at a Design Summit, which is coming up next week. Even with the great opportunity for in-person interaction at the Summit, I get the feeling there are more people wanting to “talk back” and give feedback. And certainly people want to receive feedback, to a point where they specifically bring docs to me and request publishing through the docs.openstack.org system due to the commenting system.

So what this meandering post is coming around to stating is this: You don’t need a wiki to gather feedback on your docs. Find a way to embed comments on each page and a way for collaborators to edit and you’ve got two of the basic end-goals done.

Now, make sure the end goals are known in the first place. It’s possible you need a wiki because your information would be best written a page or an article at a time. This statement is obvious when looking through your hindsight lens but difficult to be disciplined enough to state in the first place. Answer the question “why” about five levels down and it’s likely you have a solution. It may or may not be a wiki, but it’s certain that if you’re producing web content, readers have certain expectations about the content when they come to it.

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!