Open Stack

The popularity of OpenStack contributes to rapid growth of existing
projects and creation of many new projects. Most projects lack one or more
people who contribute to usable documentation. Instead, most developers
(ab)use the DocImpact flag to pass the burden to the documentation team.
The DocImpact flag generates a considerable number of documentation bugs
that include no more information than the commit message. Resolving these
bugs often requires the following:

1) Knowledge of all places in the documentation that this change impacts.
2) Ability to read and understand not only the code in the patch, but often
the architecture/design of the project.

For example, let's take a look at the first bug that appears after
searching for "docimpact" on LP:

https://bugs.launchpad.net/openstack-manuals/+bug/1255770

Best I can tell, this patch probably impacts the API documentation. Maybe
it also impacts the admin guide, user guide, and/or installation guide. The
patch contains no obvious documentation and making sense of the code
requires a deep knowledge of the project. So, I move on to another bug.
Unfortunately, most of them fall into this category.

Another fairly large number of bugs are old and potentially defunct.
Perhaps we should delete bugs for releases out of support.

Now let's take a look at Stackalytics for documentation between Grizzly and
Juno:

1) The number of commits about doubles for each release until Juno at which
point it flattens out.
2) The number of filed bugs (a significant number of DocImpact) increases
rapidly after Havana to near 1000 for Icehouse and over 1000 for Juno.
3) The percentage of resolved bugs hovers around 70-75% until Juno when it
decreases to about 60%
4) The number of significant contributors peaks at Icehouse and noticeably
decreases for Juno.

Observation:

The existing and perhaps shrinking number of documentation contributors can
no longer handle the increasing volume of changes to OpenStack let alone
creating new and improving existing content. We're still doing a great job,
but will continue to fall behind unless OpenStack makes significant,
enforceable changes to how it approaches documentation contributions from
the projects it maintains.

Ideas:

We've beaten this horse repeatedly, but never seem to act on it. OpenStack
is complex and relies heavily on great documentation to continue growth and
compete better in the market.

1) Each project elects one or more people to contribute documentation for
it. This person must know the documentation relevant to the project, know
the documentation tool chain, handle DocImpact bugs, and serve as a liaison
for other documentation issues that may impact the project.

2) The documentation team elects one or more people to focus on one or more
"books" and know the content well enough to at least triage DocImpact bugs.

3) The documentation team elects one or more people to focus on one or more
projects and know them well enough to handle most documentation issues.
This includes following project plans, patches, meetings, etc.

On Tue, Nov 4, 2014 at 3:46 AM, Lana Brindley <openstack at lanabrindley.com>
wrote:

> Hi Tom,
>
> First of all, I’m sitting in a keynote typing this out, so apologies if
> it’s a little scattered or doesn’t make sense, I haven’t given it my usual
> level of review rigour ;)
>
> Technical debt is an important thing for us to address, and I think we
> need to discuss ways in which we can effectively do that. However, the main
> reason we have so many bugs is because of the growth in OpenStack generally
> and documentation specifically. It’s not because we’re all slackers and
> suck at closing bugs. An increase in technical debt is what happens as
> small projects become big ones, and we become a more important part of the
> OpenStack ecosystem. This is a side effect of becoming bigger and better,
> which is a good thing! It’s just one of those things we need to make sure
> we continue managing.
>
> To my mind, the big value-add that docs have is information architecture.
> We, as writers, are experts in our field. We know how to effectively
> organise information, and make it accessible to as many people as possible.
> And we really, really need to get that right. If we have the right
> architecture in place, then we can get on with burning through that
> technical debt and stomping the bugs. But you can’t have one without the
> other.
>
> If we made closing bugs our primary responsibility, at the expense of all
> design architecture and those other bigger picture (and less visible)
> things we do, then we’d end up with massive books that may be technically
> accurate, but perfectly un-navigable. And I don’t want to live in that
> world.
>
> TL;DR: Let’s make sure we have the over-arching architecture right first,
> then we can make sure the right information is in the right place, and burn
> through that technical debt.
>
> Hopefully that’s more or less coherent.
>
> Lana
>
> On 4 Nov 2014, at 8:27 am, Tom Fifield <tom at openstack.org> wrote:
>
> > Hi all,
> >
> > As per Anne's recent email, I strongly oppose splitting out a new guide
> > for upgrades.
> >
> > Essentially, I don't believe there is a maintenance, discoverability or
> > contribution problem for the upgrades section of the ops guide - we've
> > done well at all of these for the past few releases. Similarly, there is
> > no problem with having different architectures with the install guide -
> > both guides have very different aims, objectives and audiences.
> >
> > However, what I want to talk with you about is slightly different to
> > those concerns.
> >
> > Normally, I wouldn't intervene in something like this, but we have a
> > massive problem in documentation that no-one seems to be talking about.
> > And, instead of fixing it, we're performing busywork like this guide
> > split :) It may create a feeling of making great progress since we're
> > doing massive wide-ranging, high-line-count changes, but we're actually
> > falling further and further behind.
> >
> > Of course, what I'm referring to is our massive bug backlog. We have
> > more than seven hundred bugs, and according to the stats from Bitergia
> > the worst performance rate at closing them than any OpenStack project by
> > a long way.
> >
> > I've watched our bug backlog from about the time it was in the dozens -
> > at that time, I could actually remember every single bug and its status
> > :) Since then, our project has grown - and our team has grown to match.
> > However, our ability to tackle the bug backlog did not improve - it got
> > worse. This problem is not just in the raw number of contributors.
> >
> > So, with such a situation as this, it causes pause to ask: why were only
> > around half of our commits in Juno related to bringing a bug to closure?
> > What were the other half doing?
> >
> > Each bug represents a problem with our documentation. Something that is
> > incorrect, or a feature that essentially will not exist for a user until
> > it is written down.
> >
> > For example, this release, we did not even manage to write up headline
> > features, such as cinder's volume replication, swift's global clusters
> > or storage policies. These features came about from strong demand from
> > our users and at the moment we're failing them badly.
> >
> > Is there anyone out there who also cares about this? Who is monitoring
> > this? Who wants to do something about this?
> >
> > Or, perhaps you'd prefer to copy and paste some more files around
> > different repositories...
> >
> >
> > ... but it's not nice to leave an email on such a note. This problem is
> > solvable, and conveniently we have an in-person meeting coming ~today.
> > Perhaps we can re-focus our efforts and priorities there, and
> > ensure they're really about delivering the most benefit for our audience.
> >
> >
> >
> > Regards,
> >
> >
> > Tom
> >
> > _______________________________________________
> > OpenStack-docs mailing list
> > OpenStack-docs at lists.openstack.org
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
> Lana Brindley
> Technical Writer
> Rackspace Cloud Builders Australia
>
>
>
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20141104/d8656454/attachment.html>