[contrib] Update docs review content

Make it less specific to openstack-manuals.

Change-Id: I58100b7ffd3aeca82be8fec1d27ba06e90a2994f

doc/doc-contrib-guide/source/doc-tools/template-generator.rst

@@ -42,12 +42,12 @@ Here are a few representative files under ``www/``:
 
 * ``de``
 
-  * ``index.html`` -- list of guides translated into $LANG*
+  * ``index.html`` -- list of guides translated into $LANG
 
 * ``errorpage.html``
 
 * ``mitaka`` -- newer series have more complex page organizations; each
-  directory is not identical*
+  directory is unique
 
   * ``admin``
 
@@ -57,7 +57,13 @@ Here are a few representative files under ``www/``:
 
     * ``index.html``
 
+  * ``de``
+
+    * ``index.html`` -- landing page for $series docs translated into $LANG
+
   * ``index.html``
+  * ``language-bindings.html``
+  * ``projects.html``
   * ``user``
 
     * ``index.html``
@@ -91,7 +97,7 @@ Here are a few representative files under ``www/``:
 
     * ``index.html``
 
-* ``project-data`` -- YAML files with data about projects in each series
+* ``project-data`` -- YAML files with data about projects in each $series
 
   * ``latest.yaml``
   * ``mitaka.yaml``
@@ -102,7 +108,7 @@ Here are a few representative files under ``www/``:
   * ``schema.yaml``
 
 * ``redirect-tests.txt`` -- input file for `whereto <http://whereto.readthedocs.io/en/latest/>`_
-  to test .htaccess;
+  to test ``.htaccess``;
   see http://files.openstack.org/docs-404s/ for a list of recent 404
   errors
 * ``static`` -- contains files that are not templates (CSS, JS,
@@ -387,8 +393,8 @@ Common tasks
 How would I change a page?
 --------------------------
 
-1. Look for the TEMPLATE_FILE value in the page source to find which
+1. Look for the ``TEMPLATE_FILE`` value in the page source to find which
-   file produces the page
+   file produces the page.
 
    The source for https://docs.openstack.org/pike/ shows:
 
@@ -440,7 +446,7 @@ modify it.
 How does the final release process work?
 ----------------------------------------
 
-See :ref:`release-task-detail`.
+See :doc:`../release/taskdetail`.
 
 Testing the build
 -----------------

doc/doc-contrib-guide/source/docs-builds.rst

@@ -24,8 +24,9 @@ create content and contribute to the documentation.
 Building output locally
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-You can use Linux, MacOS, or Windows to build the Sphinx documentation
+Although you can use Linux, MacOS, or Windows to build locally the Sphinx
-everywhere in OpenStack.
+documentation for OpenStack, Linux is the preferred build environment as it
+offers the most complete support for documentation building.
 
 OpenStack project and documentation repositories use a ``tox.ini`` file with
 specific sections that run jobs using the `Tox

doc/doc-contrib-guide/source/docs-review-guidelines.rst

@@ -193,9 +193,9 @@ wait for the next proposal run.
 The proposal job will update the patch with the next run.
 If you cannot fix the problem, ask for help on the mailing lists:
 
-* openstack-i18n: translation failures
+* openstack-i18n@lists.openstack.org: translation failures
-* openstack-doc: requirements failures, glossary sync failures,
+* openstack-dev@lists.openstack.org: requirements failures, glossary sync
-  and common content sync failures.
+  failures, and common content sync failures.
 
 Considerations for documentation aligned with release cycles
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

@@ -12,32 +12,27 @@ Reviewing documentation
 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
-<https://is.gd/openstackdocsreviewreloaded>`_. It is organized in groups based
+<https://is.gd/openstackdocsreviewreloaded>`_ or the appropriate list of
-on the audience for the documentation. To see current proposed changes, make
+Gerrit reviews for repositories with documentation.
-sure you register and log into https://review.openstack.org. For more details
+
-on the review process, see `Code Review
+The Documentation Program Dashboard only lists changes to repositories that
+are managed by the Documentation project or the project's subteams. The
+Dashboard 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 in
+OpenStack, see `Code Review
 <https://docs.openstack.org/infra/manual/developers.html#code-review>`_.
 
 Repositories and core team
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The OpenStack Documentation team is core for the openstack-manuals,
+The Documentation team is core for a number of repositories managed by the
-openstackdocstheme, and openstack-doc-tools projects.
+Documentation project subteams. A list of those subteams is available from
+:doc:`team-structure`.
 
-For the following repositories that are part of the Documentation program,
+For the security-doc repository, the rule is that each patch needs an approval
-special rules apply:
+by a Docs core and a Security core.
-
-* docs-specs: has a separate core team,
-  see :doc:`docs-specs <blueprints-and-specs>` section.
-* 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.
-* contributor-guide, 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
-`Group openstack-doc-core
-<https://review.openstack.org/#/admin/groups/30,members>`_.
 
 Reviewing a documentation patch
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -48,8 +43,13 @@ and `Code Review Guidelines
 <https://docs.openstack.org/infra/manual/developers.html#code-review>`_.
 Once done, follow the steps below to submit a patch review.
 
-#. Go to the `Documentation Program Dashboard
+#. If you want to review patches for the repositories managed by the
+   Documentation project or the project's subteams, go to the
+   `Documentation Program Dashboard
    <https://is.gd/openstackdocsreviewreloaded>`_.
+
+   To review patches for project teams' repositories, use the list of Gerrit
+   changes for the appropriate project.
 #. Select a patch set.
 #. Click a file that was uploaded to view the changes side by side.
 #. If you see some inconsistencies or have questions to the patch owner,
@@ -78,6 +78,11 @@ Once done, follow the steps below to submit a patch review.
    `Peer Review
    <https://docs.openstack.org/infra/manual/developers.html#peer-review>`_
 
+.. note::
+
+   The following information only applies to repositories managed by the
+   Documentation project.
+
 Achieving core reviewer status
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -98,23 +103,23 @@ recognizing valuable team members.
 
 The process is:
 
-* Every month (usually on the 1st), the documentation PTL draws the top 12
+* Every month (usually on the 1st), the documentation PTL draws the top
-  names from the `Stackalytics <http://stackalytics.com/>`_ report for
+  committers and reviewers from the `Stackalytics <http://stackalytics.com/>`_
-  openstack-manuals:
+  report for openstack-manuals:
 
   * `openstack-manuals Stackalytics
     <http://stackalytics.com/?module=openstack-manuals&metric=commits>`_
 
-* The PTL then consults the existing core team with a list of names to be
+* The PTL then consults the existing core team and the OpenStack community
-  removed from and added to the core list. Once an agreement is reached,
+  with a list of names to be removed from and added to the core list. This is
-  the changes are made and advertised to the main documentation mailing list.
+  done in public by using the openstack-dev@lists.openstack.org mailing list
-  Cores who are being added or removed will be contacted personally before
+  as the primary communication channel. Cores who are being removed will be
-  changes are made.
+  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:
+  with a justification sent to the openstack-dev@lists.openstack.org mailing
-  openstack-doc-core@lists.launchpad.net. Three +1 votes from other existing
+  list. Three +1 votes from other existing core team members must be achieved
-  core team members must be achieved for approval.
+  for approval.
 
 Core reviewer responsibilities
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

doc/doc-contrib-guide/source/release.rst

@@ -8,7 +8,9 @@ This section describes the tasks that need to be completed to publish the
 documentation for an OpenStack release. It is intended to be used by the
 PTL and release managers.
 
-Pike release managers are Chason Chan and Petr Kovar.
+The current release manager for Documentation is listed on the
+`Cross Project Liaisons wiki page
+<https://wiki.openstack.org/wiki/CrossProjectLiaisons#Release_management>`_.
 
 .. toctree::
    :maxdepth: 2

doc/doc-contrib-guide/source/team-structure.rst

@@ -27,8 +27,13 @@ with their respective leads:
 The current list of docs cores for openstack-manuals, openstackdocstheme,
 and openstack-doc-tools repositories can be found at
 https://review.openstack.org/#/admin/groups/30,members.
+
 The api-site, contributor-guide, docs-specs, security-doc, training-guides,
-and training-labs repositories have separate core teams.
+and training-labs repositories have separate core teams but also include the
+openstack-manuals core team.
+
+The docs-specs repository has a separate core team, see
+:doc:`blueprints-and-specs` for details.
 
 The cross-project liaisons (CPLs) assist with subject matter questions,
 reviews, doc bug triaging, and patching docs.