[nova][ptg] Documentation in nova

Artom Lifshitz alifshit at redhat.com
Mon May 25 13:15:38 UTC 2020


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).

>
> Cheers,
> gibi
>
> >
> > Pros:
> >
> > * Documentation gets better
> > * I can iterate *much* faster
> >
> > Cons:
> >
> >  * Possibility of mistakes or "bad documentation is worse than no
> >    documentation"
> >     * Counterpoint: Our documentation is already bad/wrong and is
> >       getting worse due to bitrot.
> >  * Better is subjective
> >     * Counterpoints: The general structure of the patches I listed
> >       above was accepted in each case, I have other projects I have
> >       authored to point to (e.g. patchwork.readthedocs.io/)
> >  * Merge conflicts
> >     * Counterpoint: It's docs. Just drop these (non-functional) hunks
> >       if it's awkward.
> >
> >
> >
>
>
>




More information about the openstack-discuss mailing list