openstack-doc-core team mailing list archive

[Lana Brindley <openstack@xxxxxxxxxxxxxxxx>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi core team,

Digging up this old thread to let you all know that I've created a
blueprint and spec for this:

https://blueprints.launchpad.net/openstack-manuals/+spec/review-docimpac
t
https://review.openstack.org/#/c/224420/

It's marked WIP for now, to give us a chance to discuss it. I'll also be
sending a heads up about this to the docs list.

L


On 25/06/15 12:03, Lana Brindley wrote:
> Hi core team,
> 
> One of the things that came up as a pain point at Summit was the DocIm
pact automation. I’ve been doing some thinking about this, and this is w
here 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 'DocImpac
t' 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 assump
tion that the documentation fairy comes along and takes care of things.
In reality, what then happens is some docs triager spends an hour lookin
g at the patch, searching through the docs, then deciding it has nothing
 to do with openstack-manuals. Often, the actual doc impact (if there ev
en 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. Wha
t really happens is that those bugs are largely irrelevant for openstack
- -manuals, which puts pressure on our core team to triage them effectivel
y. 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 D
ocImpact 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.
> 
> So, solutions:
> 
> 1: We have a crack team of docs people (potentially with automation as
sistance) going through docimpact bugs, cc'ing the original patch author
s, and moving them into dev repos where necessarily, and marking the res
t invalid. We could team this with a an education campaign on the dev ma
iling list.
> 
> 2: We ditch docimpact, and force devs to create their own docs bugs (a
nd patches). This would mean fewer devs get on with the job of documenta
tion, 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 t
he openstack-manuals doc queue. Maintenance overhead then remains with d
ev, and I bet you any money they would self-police that better than we e
ver could.
> 
> 4: Some other thing I haven’t thought of yet … ?
> 
> I have a feeling 3 is where the money's at. I took the liberty of quic
kly checking with an Infra core, and this change should be relatively ea
sy to implement, too, for the record.
> 
> Thoughts?
> 
> Lana
> 
> Lana Brindley
> Technical Writer
> Rackspace Cloud Builders Australia
> 
> 
> 
> 
> 


- -- 
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
http://lanabrindley.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.22 (GNU/Linux)

iQEcBAEBAgAGBQJV+kxnAAoJELppzVb4+KUy9m4IAIsN6kcSF44t9vVvz6TOh1wt
LaonazTjiJNbVAIDHVr7MgkZJQABGL7QBNaH9mvjISOKqfdlNu0oPQ1PQQDg7ViE
8kQKsQaFI7b4/00rgNUvQYYN8Z0/mmRLLa3MbP15BjgLBjuYR0xFQXJV3LXOpF0B
TuhH+uQsC/vjMSXKrY+PmU/mzqH6AZqROXTKM/MoxFw52AmvmQ/yt2xft59xKr1o
BvdYPgd1csEWZGcNwUP07V3mEHwtl5VTeB72LOlmm6eJZwMLXgogXVyVNOQnsjhe
m8WtX/34EiR80jfddJc1UiMrBc34HWYR4/I2MtO11jXz1ORlNBjYrwJ4ry0YxXk=
=bFDh
-----END PGP SIGNATURE-----