Open Stack

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.

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