Open Stack

On 24 November 2015 at 13:11, Lana Brindley <openstack at lanabrindley.com>
wrote:

> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA256
>
> 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].

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.

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.

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.

Thanks,
Armando

[1] https://github.com/openstack/neutron/tree/master/doc
[2] http://docs.openstack.org/developer/neutron/
[3] http://docs.openstack.org/networking-guide/
[4] http://docs.openstack.org/developer/openstack-projects.html
[5] https://review.openstack.org/#/c/248515/2/gerrit/projects.yaml


> In the rare instance that that isn't the case, and it needs to come into
> one of the openstack-manuals docs, then we are happy to discuss the issue
> with the person who raised the bug and, possibly, take the bug in our queue
> to be fixed.
>
> To be clear: just because DocImpact raises a bug in a projects' queue,
> doesn't mean docs aren't available to help fix it. We're always here for
> you to ask questions about docs bugs, even if those bugs are in your repo
> and your developer documentation.


> I hope that answers the question.
>
> Thanks,
> Lana
>
> On 24/11/15 16:07, Akihiro Motoki wrote:
> > it sounds a good idea in general.
> >
> > One question is how each project team should handle DocImpact bugs
> > filed in their own project.
> > It will be a part of "Plan and implement an education campaign"
> > mentioned in the docs spec.
> > I think some guidance will be needed. One usual question will be which
> > guide(s) needs to be updated?
> > openstack-manuals now have a lot of manuals and most developers are
> > not aware of all of them.
> >
> > Akihiro
> >
> >
> > 2015-11-24 7:33 GMT+09:00 Lana Brindley <openstack at lanabrindley.com>:
> > Hi everyone,
> >
> > The DocImpact flag was implemented back in Havana to make it easier for
> developers to notify the documentation team when a patch might cause a
> change in the docs. This has had an overwhelming response, resulting in a
> huge amount of technical debt for the docs team, so we've been working on a
> plan to change how DocImpact works. This way, instead of just creating a
> lot of noise, it will hopefully go back to being a useful tool. This is
> written in more detail in our spec[1], but this email attempts to hit the
> highlights for you.
> >
> > TL;DR: In the future, you will need to add a description whenever you
> add a DocImpact flag in your commit message.
> >
> > Right now, if you create a patch and include 'DocImpact' in the commit
> message, Infra raises a bug in either the openstack-manuals queue, or (for
> some projects) your own project queue. DocImpact is capable of handling a
> description field, but this is rarely used. Instead, docs writers are
> having to dig through your patch to determine what (if any) change is
> required.
> >
> > What we are now implementing has two main facets:
> >
> > * The DocImpact flag can only be used if it includes a description. A
> Jenkins job will test for this, and if you include DocImpact without a
> description, the job will fail. The description can be a short note about
> what needs changing in the docs, a link to a gist or etherpad with more
> information, or a note about the location of incorrect docs. There are
> specific examples in the spec[2].
> > * Only Nova, Swift, Glance, Keystone, and Cinder will have DocImpact
> bugs created in the openstack-manuals queue. All other projects will have
> DocImpact bugs raised in their own queue. This is handled in [3] and [4].
> >
> > This will hopefully reduce the volume of DocImpact bugs being created in
> the openstack-manuals queue, and also improve the quality of the bugs that
> are created.
> >
> > I know there is a fair amount of confusion over DocImpact already, so
> I'm more than happy to field questions on this.
> >
> > Thanks,
> > Lana
> >
> >
> > 1:
> http://specs.openstack.org/openstack/docs-specs/specs/mitaka/review-docimpact.html
> > 2:
> http://specs.openstack.org/openstack/docs-specs/specs/mitaka/review-docimpact.html#examples
> > 3: https://review.openstack.org/#/c/248515/
> > 4: https://review.openstack.org/#/c/248549/
> >
> >>
> >> _______________________________________________
> >> Openstack-i18n mailing list
> >> Openstack-i18n at lists.openstack.org
> >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n
>
> - --
> 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/
>
> iQEcBAEBCAAGBQJWVNJrAAoJELppzVb4+KUy0ggIALEv0MaKfubZZ4wpyUZnWBsb
> QqTTufVJZ8o/p6CanDkFl4EnyaAtsmoe/hYIlmqDMxWCDichIB829G11WjfHZz/H
> g6tsUar640bHs2XSh8MTtkTYY5wX2MIL+2FMqIioCSn7rGc/AXBdDRhqp8HYJBoX
> yP8PM6uSYQIEzYfmwQ4McZaRmXfPfqnvB+AWcmf96/nwYvndSk+WrELR6vQmhoIf
> mWKkdpwtp6sNJ0DYkxwhWjEE5e6bbQ2mnYz+gKGsptoTl8GwxiGWJjakPn6fzKhr
> CJ+ofXtOp2PNS4GzQiJrt6sHKgLiXGGQ0iCGn2BqPZqWLjKenWPGmeg2Ybgm6Y8=
> =4dRC
> -----END PGP SIGNATURE-----
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20151201/78cdd735/attachment-0001.html>