Open Stack

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