openstack-doc-core team mailing list archive

[Anne Gentle <anne@xxxxxxxxxxxxx>]

On Wed, Jun 24, 2015 at 9:03 PM, Lana Brindley <openstack@xxxxxxxxxxxxxxxx>
wrote:

> Hi core team,
>
> One of the things that came up as a pain point at Summit was the DocImpact
> automation. I’ve been doing some thinking about this, and this is where I’m
> at right now:
>
> Workflow: Devs create a patch, and at commit time they think "oh yeah,
> probably there should be some docs about that" and whack in a 'DocImpact'
> flag. In other words, there's not a lot of thought going in here, it's just
> an easy thing to do, they get a warm fuzzy, and there’s an assumption that
> the documentation fairy comes along and takes care of things. In reality,
> what then happens is some docs triager spends an hour looking at the patch,
> searching through the docs, then deciding it has nothing to do with
> openstack-manuals. Often, the actual doc impact (if there even is one) is
> against docs in the dev repo, not openstack-manuals.
>
> In short, devs recognise they need docs, and DocImpact is an easy way to
> feel like they're doing something productive to make that happen. What
> really happens is that those bugs are largely irrelevant for
> openstack-manuals, which puts pressure on our core team to triage them
> effectively. To try and get some perspective on the size of the problem,
> here are some numbers:
>
> Of the 508 current openstack-manuals bugs, 214 are the result of the
> DocImpact script. 51 of these are yet to be triaged.
> Right now, there are 170 patches in-flight with the DocImpact tag. To
> state the obvious, if all them land, that’s 170 new bugs in our queue.
>

Well, last year I made an attempt to get fewer DocImpact bugs in the
openstack-manuals queue. But yes, this is generally accurate. Also it's
really only set up to log to openstack-manuals for about five projects, the
ones that came later are logging against their own project like Fuel.


>
> So, solutions:
>
> 1: We have a crack team of docs people (potentially with automation
> assistance) going through docimpact bugs, cc'ing the original patch
> authors, and moving them into dev repos where necessarily, and marking the
> rest invalid. We could team this with a an education campaign on the dev
> mailing list.
>
> 2: We ditch docimpact, and force devs to create their own docs bugs (and
> patches). This would mean fewer devs get on with the job of documentation,
> but at least what we do get would be well-considered, rather than hastily
> added to their commit message.
>
> 3: We adjust docimpact to raise a bug in their own dev repo. So, patch
> against swift with docimpact raises a bug in the swift bug queue, not the
> openstack-manuals doc queue. Maintenance overhead then remains with dev,
> and I bet you any money they would self-police that better than we ever
> could.
>

This is the direction I envisioned, but let's talk through it a little more
for some of the larger projects. For example, a DocImpact patch that
affects the config ref for nova, how do we track that it's complete if it's
logged against nova? There are probably ways to handle this, and
Launchpad's API could help. It just involves more coordination at release
time for release-sensitive DocImpact.


>
> 4: Some other thing I haven’t thought of yet … ?
>

For the API Working Group, APIImpact is a flag that becomes a review
request and not a bug. At each weekly meeting, they have an agenda item to
review patches with APIImpact. This helps the developers get a better
patch, ensures API consumers are protected, and lets the API working group
consider whether guidelines are already in place or need to be written in
order to accurately review the patch. I'd like to see this approach
included in our process (even if we are "way behind" in numbers).

So, my proposal would be a combination:
 - keep DocImpact
 - use DocImpact for reviews both at weekly meetings and in day-to-day
review dashboards
 - log bugs with DocImpact against the product with a way to aggregate at
release time

Might need a small spec, perhaps in openstack-specs, to make sure we
communicate the chosen approach widely. Also that lets you easily bring it
up at a cross-project meeting.

If you like, I can create a new docs dashboard that contains
DocImpact-flagged patches. Let me know your thoughts.

Thanks,
Anne


>
> I have a feeling 3 is where the money's at. I took the liberty of quickly
> checking with an Infra core, and this change should be relatively easy to
> implement, too, for the record.
>
> Thoughts?
>
> Lana
>
> Lana Brindley
> Technical Writer
> Rackspace Cloud Builders Australia
>
>
>
>
> --
> Mailing list: https://launchpad.net/~openstack-doc-core
> Post to     : openstack-doc-core@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack-doc-core
> More help   : https://help.launchpad.net/ListHelp
>
>