Add documentation for documentation contributions

Missing from our contributor guides is documentation guidelines,
starting a page there for now especially as there are a couple of
things that emerged in the great pike import that would be good to
write down.

Part of bp: doc-migration

Change-Id: Ib2b49f70c55311195535a5ef250ff555e227fa0a

doc/source/contributor/documentation.rst

@@ -0,0 +1,91 @@
+===========================
+ Documentation Guide Lines
+===========================
+
+These are some basic guidelines in contributing to documentation in Nova.
+
+Review Guidelines
+=================
+
+Documentation only patches differ from code patches in a few ways.
+
+* They are often written by users / operators that aren't plugged into daily
+  cycles of nova or on irc.
+* Outstanding patches are far more likely to trigger merge conflict in git than
+  code patches.
+* There may be wide variation on points of view of what the "best" or
+  "clearest" way is to say a thing.
+
+This all can lead to a large number of practical documentation improvements
+stalling out because the author submitted the fix, and does not have the time
+to merge conflict chase or is used to the gerrit follow up model.
+
+As such documentation patches should be evaluated in the basic context of "does
+this make things better than the current tree". Patches are cheap, it can
+always be further enhanced in future patches.
+
+Typo / trivial documentation only fixes should get approved with a single +2.
+
+How users consume docs
+======================
+
+The current primary target for all documentation in nova is the web. While it
+is theoretically possible to generate pdf versions of the content, the tree is
+not currently well structured for that, and it's not clear there is an audience
+for that.
+
+The main nova docs tree ``doc/source`` is published per release, so there will
+be copies of all of this as both the ``latest`` url (which is master), and for
+every stable release (e.g. ``pike``).
+
+.. note::
+
+   This raises an interesting an unexplored question about whether we want all
+   of ``doc/source`` published with stable branches that will be stale and
+   unimproved as we address content in ``latest``.
+
+The ``api-ref`` and ``api-guide`` publish only from master to a single site on
+developer.openstack.org. As such they are effectively branchless.
+
+Guidelines for consumable docs
+==============================
+
+* Give users context before following a link.
+
+  Most users exploring our documentation will be trying to learn about our
+  software. Entry and subpages that provide links to in depth topics need to
+  provide some basic context about why someone would need to know about a
+  ``filter scheduler`` before following the link named filter scheduler.
+
+  Providing these summaries helps the new consumer come up to speed more
+  quickly.
+
+* Doc moves require .htaccess redirects
+
+  If a file is moved in a documentation source tree, we should be aware that it
+  might be linked from external sources, and is now a ``404 Not Found`` error
+  for real users.
+
+  All doc moves should include an entry in ``doc/source/_extra/.htaccess`` to
+  redirect from the old page to the new page.
+
+* Images are good, please provide source
+
+  An image is worth a 1000 words, but can go stale pretty quickly. We ideally
+  want ``png`` files for display on the web, but that's a non modifiable
+  format. For any new diagram contributions we should also get some kind of
+  source format (``svg`` is ideal as it can be modified with open tools) along
+  with ``png`` formats.
+
+Long Term TODOs
+===============
+
+* Sort out our toctree / sidebar navigation
+
+  During the bulk import of the install, admin, config guides we started with a
+  unified toctree, which was a ton of entries, and made the navigation sidebar
+  in Nova incredibly confusing. The short term fix was to just make that almost
+  entirely hidden and rely on structured landing and sub pages.
+
+  Long term it would be good to reconcile the toctree / sidebar into something
+  that feels coherent.

doc/source/contributor/index.rst

@@ -48,6 +48,8 @@ For Reviewers
   when doing code review in Nova, especially some things that are hard to test
   for, but need human eyes.
 * :doc:`/reference/i18n`: what we require for i18n in patches
+* :doc:`/contributor/documentation`: Guidelines for handling documentation
+  contributions
 
 Testing
 =======

doc/source/index.rst

@@ -225,6 +225,7 @@ looking parts of our architecture. These are collected below.
    contributor/api-2
    contributor/blueprints
    contributor/code-review
+   contributor/documentation
    contributor/microversions
    contributor/placement.rst
    contributor/policies.rst