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

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

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 Brindley
Technical Writer
Rackspace Cloud Builders Australia
Version: GnuPG v2
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/


More information about the Openstack-i18n mailing list