[OpenStack-docs] [openstack-dev] [Openstack-i18n] DocImpact Changes

Lana Brindley openstack at lanabrindley.com
Wed Dec 2 03:09:36 UTC 2015


-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On 02/12/15 12:53, Armando M. wrote:
> On 24 November 2015 at 13:11, Lana Brindley <openstack at lanabrindley.com>
> wrote:
> 
> Hi Akihiro,
> 
> Judging by most of the bugs we see in the openstack-manuals queue, the
> bugs that will be raised in projects' own queues will usually be against
> their own developer documentation.
> 
> 
>> I am a bit confused. The developer documentation coexists with the code
>> that's being patched. Is this the documentation you're referring to? So for
>> instance in Neutron we have [1] rendered into [2].

That's correct.

> 
>> I always assumed that DocImpact was needed to flag configuration changes,
>> and more generally user facing issues, and these are not captured in the
>> developer doc [2] (afaik, *-aas services do have a developer documentation
>> but no entry point in [4]), as developers are not the audience, but rather
>> guide [3]. On the other hand, if patches do require dev doc changes (like
>> design issues etc), reviewers tend to ask to take care of them in the
>> context of the same patch, without the burden of going through an extra bug
>> report.

I agree, and that was the original intention, however it doesn't get used that way in the majority of cases we see. Feel free to use DocImpact (with a description), and then manually flip the bug to openstack-manuals in this case.

> 
>> So the fact that Neutron's DocImpact changes raises a bug report in LP
>> Neutron seems counterintuitive, and I am a bit at loss here. Can you
>> elaborate on what was the rationale for making only certain projects target
>> their own queues? I wouldn't want to have bug reports be reassigned to the
>> right queue only to cause more burden that this initiative originally
>> intended to relieve.

We chose the five 'defcore' projects here, as they are the ones that are formally (and most extensively) documented in openstack-manuals.

> 
>> Having said that, let's assume we are stricter about what gets flagged with
>> DocImpact, would you be open to revisiting the doc group for Neutron as set
>> in [5]? In the meantime, I'll go ahead and look at the outstanding patches
>> and bug reports recently filed to sanitize with the best of my abilities.

As we noted in the original spec, we appreciate that Neutron is on the cusp of being considered 'defcore', and we're happy to include it once that has happened formally.

Thanks for your help.

Lana

- -- 
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
http://lanabrindley.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQEcBAEBCAAGBQJWXmDwAAoJELppzVb4+KUyezMH/3WuKrW+8Py9XU3o2vddCK4c
ZovehU0Xq1mHzzpfh8Vfc71MfJVAtotr9Lt0Vd5b4jAnjSWz7QI4/W2CG3d+aM+L
FYPDn9koTC/+EsXlz8ekzLQUz6PToa21jfdmcg6tSAPA09FV5j7SPWIPXD9bvzun
q9NWhs3jjj4hVtgUhmFdeC7B0vDzT6EWU2kAuSWwUEf7z2c3S7ZnuteyOKLf6aLZ
rRbZi59ras8/3jI9EY8h6Wk47gQ3fLwvYyL/tHU9c2jOGPPz47f7HKaXVO0MQ58p
E4V3nhGEITt3NMQH8m0IEW7JLd3tRX1C7ERKK05+k5yl7dirxKsysq52xJh0EMo=
=1mW1
-----END PGP SIGNATURE-----



More information about the OpenStack-docs mailing list