On Mon, May 25, 2020 at 7:48 AM Balázs Gibizer <balazs.gibizer@est.tech> wrote:
On Fri, May 22, 2020 at 21:51, Stephen Finucane <stephenfin@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.