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.