[nova][ptg] Documentation in nova

John Garbutt john at johngarbutt.com
Mon Jun 1 09:56:04 UTC 2020


On Mon, 25 May 2020 at 15:30, Balázs Gibizer <balazs.gibizer at est.tech> wrote:
> On Mon, May 25, 2020 at 09:15, Artom Lifshitz <alifshit at redhat.com>
> wrote:
> > On Mon, May 25, 2020 at 7:48 AM Balázs Gibizer
> > <balazs.gibizer at est.tech> wrote:
> >>
> >>
> >>
> >>  On Fri, May 22, 2020 at 21:51, Stephen Finucane
> >> <stephenfin at redhat.com>
> >>  wrote:
> >>  > Hi,
> >>  >
> >>  > [This is a topic from the PTG etherpad [0]. As the PTG time is
> >>  > intentionally kept short, let's try to discuss it or even
> >> conclude it
> >>  > before the PTG]
> >>  >
> >>  > Our documentation in nova is suffering from bit rot, the ongoing
> >>  > effects of the documentation migration during Pike (I think), and
> >>  > general lack of attention. I've been working to tackle this but
> >>  > progress has been very slow. I suggested this a couple of PTGs
> >> ago,
> >>  > but
> >>  > once again I'd like to explore going on a solo run with these by
> >>  > writing and self-approving (perhaps after a agreed interval)
> >>  > *multiple*
> >>  > large doc refactors. I've left some notes below, copied from the
> >>  > Etherpad, but in summary I believe this is the only realistic way
> >> we
> >>  > will ever be able to fix our documentation.
> >>  >
> >>  > Cheers,
> >>  > Stephen
> >>  >
> >>  > [0] https://etherpad.opendev.org/p/nova-victoria-ptg
> >>  >
> >>  > ---
> >>  >
> >>  > Documentation reviews are appreciated but are generally seen as
> >> low
> >>  > priority. See:
> >>  >
> >>  >   * https://review.opendev.org/667165 (docs: Rewrite quotas
> >>  > documentation)
> >>  >   * https://review.opendev.org/667133 (docs: Rewrite host
> >> aggregate,
> >>  > availability zone docs)
> >>  >   * https://review.opendev.org/664396 (docs: Document how to
> >> revert,
> >>  > confirm a cold migration)
> >>  >   * https://review.opendev.org/635243 (docs: Rework the PCI
> >>  > passthrough
> >>  > guides)
> >>  >   * https://review.opendev.org/640730 (docs: Rework all things
> >>  > metadata'y)
> >>  >   * https://review.opendev.org/625878 (doc: Rework 'resize' user
> >> doc)
> >>  >   * ...
> >>  >
> >>
> >>  Thank you working on all these documentations.
> >>
> >>  > I (stephenfin) want permission to iterate on documentation and
> >> merge
> >>  > unilaterally unless someone expresses a clear interest
> >>
> >>  Honestly, self approve feels scary to me as it creates precedent.
> >> I'm
> >>  happy to get pinged, pushed, harassed into reviewing the doc patches
> >>  instead.
> >
> > Agreed. FWIW, I'm willing to review those as well (though obviously my
> > +1 won't be enough to do anything on its own).
>
> I can be convinced to easy up the rules for pure doc patches. Maybe one
> +2 would be enough for pure doc patches to merge if there are +1 from
> SMEs on the patch too.

I would prefer one +2 rather than self approve.
Totally hear you on the cycle time though.

Last cycle I made policy a big review priority for me.
I am not against making docs a review priority for me this time(*),
given this can make a big difference for operators.
(* I have not yet my mind up where I can make the biggest difference)

Thanks,
johnthetubaguy



More information about the openstack-discuss mailing list