Contributor Guide miscellaneous process updates

Working from the Newton docs deliverables list from the Austin Summit:
* Who should follow this guide?
* Introduction of a minimal review time?
* Section about contribution recommendations: what devs should
  contribute, review expectations of docs, expected turn-around time, etc.
* How to deprecate/remove docs?
* Also define which are continuous-release, versioned, etc.

Change-Id: I9df39977a8e9ca81960c6ee8840e864054d9b1d2

doc/contributor-guide/source/blueprints-and-specs.rst

@@ -51,6 +51,18 @@ To patch for the release-specific documentation, you should generally patch to
 master branch with "backport: xxxx" (for example, backport: kilo) in the commit
 message.
 
+For these guides, the docs.openstack.org site defaults to the current release,
+with the previous two releases being available under the ``More Releases
+& Languages`` drop-down. At release time, the documentation release team
+will update the default page to the new release, and remove the link to
+the oldest release. These docs are still available online for people who
+have direct URLs to the content, but they are no longer linked from the
+main site. For books written in DocBook XML, these old versions are clearly
+marked with the release name in red down the left-hand margin. We are
+currently developing a similar method of marking older books written in RST.
+The core team tracks usage of older versions, and as usage falls, can
+remove them entirely.
+
 Installation Guides
 -------------------
 

doc/contributor-guide/source/docs-review.rst

@@ -9,14 +9,13 @@ Reviewing documentation
 
    docs-review-guidelines.rst
 
-OpenStack documentation is treated like code.
-We follow the standard code review process.
-To see what documentation changes are ready for review, use the
-`Documentation Program Dashboard <http://is.gd/openstackdocsreview>`_.
-It is organized in groupings based on the audience for the documentation.
-To see current proposed changes, make sure you register and
-log into https://review.openstack.org.
-For more details on the review process, see `Code Review
+OpenStack documentation is treated in the same way as code, and follows the
+standard code review process. To see what documentation changes are ready for
+review, use the `Documentation Program Dashboard
+<http://is.gd/openstackdocsreview>`_. It is organized in groups based on the
+audience for the documentation. To see current proposed changes, make sure
+you register and log into https://review.openstack.org. For more details on
+the review process, see `Code Review
 <http://docs.openstack.org/infra/manual/developers.html#code-review>`_.
 
 Repositories and core team
@@ -33,8 +32,8 @@ special rules apply:
 * security-doc: has a separate core team consisting of Docs team members and
   Security team members. The rule here is that each patch needs an approval
   by a Docs core and a Security core.
-* training-guides: has a separate core team.
-* training-labs: has a separate core team.
+* training-guides and training-labs: have separate core teams, but also
+  includes the openstack-manuals core team.
 
 The current list of docs cores for openstack-manuals can be found at
 https://review.openstack.org/#/admin/groups/30,members.
@@ -78,32 +77,23 @@ Once done, follow the steps below to submit a patch review.
    `Peer Review
    <http://docs.openstack.org/infra/manual/developers.html#peer-review>`_
 
-Achieving a core reviewer status
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Achieving core reviewer status
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Core reviewers are able to +2 and merge content into the projects they
-have the core status in. Core status is granted to **those who have not
+have core status in. Core status is granted to those who have not
 only done a sufficient quantity of reviews, but who also have shown care
-and wisdom in those reviews**. Becoming a core reviewer also carries with
-it a responsibility: you are now the **guardian of the gate**, and
-it is up to the core team to ensure that nothing unfavorable gets through,
-without discouraging contributions.
-The core reviewer's role is complex, and having a great core team is
-crucial to the success of any OpenStack project.
+and wisdom in those reviews.
 
-With great power comes great responsibility.
-
-For this reason, we want to ensure that we have a suitably small team of
-core reviewers, but that each core reviewer we have is active and engaged.
-In order to do this, we changed the process for achieving core reviewer
-status to ensure there was a good mix between a statistics-based and
-nomination-based approach. This means a couple of things:
-
-* The core team changes slightly faster than before, with inactive core
-  team members being removed and new, active core team members being added
-  on a more regular basis.
-* Now, the existing core team can act faster on recognizing valuable team
-  members.
+The core reviewer's role is complex, and having a great core team is crucial
+to the success of any OpenStack project. The documentation team aims to have
+a suitably small team of core reviewers, with each core reviewer being active
+and engaged. The process for appointing core reviewers aims to ensure there
+is a good mix between a statistics-based and nomination-based approach. To
+this end, the core team changes relatively quickly, with inactive core team
+members being removed and new, active core team members being added on a
+regular basis. This also allows the existing core team to act quickly on
+recognizing valuable team members.
 
 The process is:
 
@@ -117,9 +107,62 @@ The process is:
 * The PTL then consults the existing core team with a list of names to be
   removed from and added to the core list. Once an agreement is reached,
   the changes are made and advertised to the main documentation mailing list.
-  Cores who are being removed will be contacted personally before removal.
+  Cores who are being added or removed will be contacted personally before
+  changes are made.
 
 * Existing core team members can nominate a new core member at any time,
   with a justification sent to the existing core team:
   openstack-doc-core@lists.launchpad.net. Three +1 votes from other existing
   core team members must be achieved for approval.
+
+Core reviewer responsibilities
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Becoming a core reviewer carries with it a responsibility: you are now the
+guardian of the gate, and it is up to the core team to ensure that nothing
+unfavorable gets through, without discouraging contributions.
+
+General instructions for being a core reviewer are located in the
+`Core Reviewer's Guide
+<http://docs.openstack.org/infra/manual/developers.html#code-review>`_.
+This section is for openstack-manuals core reviewers.
+
+In almost all cases, patches can be merged with at least one +1 vote, and
+two +2 votes. The second +2 vote is usually the one that will also merge the
+patch (often referred to as a +2A vote). There are very few exceptions to
+this rule within documentation, the main one being extraordinary
+circumstances where a patch has broken the build and a fix is required very
+quickly. In this case, you should still seek out another core team member
+if possible, and make some kind of contact with the PTL so that they are
+aware of the problem.
+
+If you are a core team member, but don't feel you understand the subject
+matter of a patch well enough to confidently merge it, vote +1 and mention
+your reasons. Being overly cautious is better than being overly confident.
+
+Try not to merge a patch too quickly, even if it strictly has the correct
+number of votes. Allowing a patch to sit for a couple of days is generally
+helpful, in order to ensure enough people have seen the change. It can also
+be valuable to add speciality team leads or other subject matter experts
+to patches where you feel more specialized knowledge is required to make
+a good decision.
+
+A note on review rigor: There are very few guidelines about what a good patch
+looks like, but the general approach is that if it's technically accurate and
+better than the existing content, then it should be approved. The main things
+to look for:
+
+* General spelling and grammar.
+* Technical accuracy. Where possible, test commands on your own VM to make
+  sure they're accurate. Check any related bugs and mailing list conversation
+  to see if there's anything else you might need to take into account.
+* The 'is it better than what we have already' test. Check the diff, or look
+  at the current document on the doc site, and determine if the changes are
+  an improvement. Provide corrections in-line for the author to fix if
+  there's more than a couple of errors. If there's just one or two really
+  minor changes (or in a situation where the writer has explicitly asked for
+  editorial assistance), consider checking out the patch and editing it
+  yourself.
+
+And, as a final note: Be nice. Be helpful. It is your job as a core reviewer
+to help people get patches merged, not block them.

doc/contributor-guide/source/index.rst

@@ -5,8 +5,8 @@ OpenStack Documentation Contributor Guide
 Abstract
 ~~~~~~~~
 
-This guide provides detailed instructions on the documentation contribution
-workflow and conventions to be considered by all contributors. Please
+This guide provides detailed instructions on the contribution workflow and
+conventions to be considered by all documentation contributors. Please
 follow these guidelines to keep the documentation structure, style, and
 syntax consistent.
 

doc/contributor-guide/source/quickstart/developers.rst

@@ -13,3 +13,31 @@ Many of these types of changes are handled automatically by
 ``openstack-doc-tools``, and published to the Configuration Reference
 and Command-Line Reference. For more information about these automated
 tools, see the :ref:`doc-tools` chapter.
+
+If you are contributing documentation to the main openstack-manuals
+repository, there are a few things you can do to help your patch merge
+quickly and easily:
+
+* Contact your project's documentation `cross-project liaison
+  <https://wiki.openstack.org/wiki/CrossProjectLiaisons#Documentation>`_.
+  They can help you with finding the appropriate book to add your patch, and
+  the relevant people to review your patch once you have written it.
+* If you are not confident in your written English skills, feel free to
+  add a note that you are happy to have editorial assistance on the patch.
+  This will encourage writers to check out your patch and correct any
+  spelling or grammar mistakes, rather than just adding comments for you
+  to fix yourself.
+* If you know which book you want to modify, get in contact with the
+  appropriate speciality team, listed at :doc:`../team-structure`. They
+  can help you determine where the content should live, and also give you
+  details about upcoming changes to the architecture of those books that
+  might affect your new documentation.
+* If you are intending to make a very large change, such as an entirely
+  new section or chapter, or documenting a new project, the core team might
+  ask you to create a blueprint and specification for the change. If you are
+  unsure whether your change will require a blueprint or specification, ask
+  on the mailing list for guidance.
+* If you want to create a new Installation Tutorial for your big tent
+  project, see :doc:`../project-install-guide`.
+* Remember, you can always contact the documentation team through our mailing
+  list, or on IRC.

doc/contributor-guide/source/quickstart/first-timers.rst

@@ -5,7 +5,7 @@ First timers
 ============
 
 One of the best ways to start contributing to OpenStack documentation
-is to walk through the Installation guide and complete it by hand.
+is to walk through the Installation Tutorial and complete it by hand.
 Keep notes as you go, and offer suggestions for improvement by filing
 documentation bugs at Launchpad.
 

doc/contributor-guide/source/quickstart/new-projects.rst

@@ -19,11 +19,6 @@ Any configuration options or command line tools should be documented using
 the automated ``openstack-doc-tools``. For more information about these
 automated tools, see the :ref:`doc-tools` chapter.
 
-To create your Installation documentation in accordance with the OpenStack
-Foundation Project Navigator, begin by drafting and polishing it in your
-developer documentation repository. This is considered 'official' Installation
-documentation for the purposes of the Navigator. Once you have a good amount
-of quality content, open a conversation with the openstack-manuals team about
-inclusion in the top level documentation directory. The docs team will then be
-able to work with you to determine your specific documentation needs, and the
-best way to include your project in openstack-manuals.
+To create an Installation Tutorial in accordance with the OpenStack
+Foundation Project Navigator, follow the instructions at
+``project-install-guide``.