Open Stack

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.