[nova][ptg] Documentation in nova
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) * ... I (stephenfin) want permission to iterate on documentation and merge unilaterally unless someone expresses a clear interest 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.
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. 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.
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.
On Mon, May 25, 2020 at 09:15, Artom Lifshitz <alifshit@redhat.com> wrote:
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).
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.
On Mon, 25 May 2020 at 15:30, Balázs Gibizer <balazs.gibizer@est.tech> wrote:
On Mon, May 25, 2020 at 09:15, Artom Lifshitz <alifshit@redhat.com> wrote:
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).
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
participants (4)
-
Artom Lifshitz
-
Balázs Gibizer
-
John Garbutt
-
Stephen Finucane