Sneaking a peek at the numbers for documentation along with the code should show us pointers about docs keeping up with code. As I suspected, there were about three major contributors to the operations manuals that span all the projects, and about three major contributors to the API docs. Also not a big surprise, I am the major contributor to both. My spidey sense felt it but I had a real gut check with the actual data.
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.