Open Stack

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.

Cheers,
gibi

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