Open Stack

I hope you don't mind a repost of my blog entry, but I'd like this to be a
conversation starter. Comment on the list or on the blog, I'm listening. :)

>From http://justwriteclick.com/2013/04/26/who-wrote-openstack-grizzly-docs/

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. 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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20130426/0c7c0d30/attachment.html>