Explain new project specific doc layout

First version of moving some content from the migration spec to the
Contributor Guide to serve as reference on how projects should set up
their directories.

It also explains how to link to the landing pages.

Change-Id: I9c815650a19d6d67d89301fa36d795c590be331d

doc/contributor-guide/source/landing-pages.rst

@@ -0,0 +1,17 @@
+=============
+Landing pages
+=============
+
+There are now central landing pages for the various project guides
+like one central place for the admin guide at
+https://docs.openstack.org/pike/admin/index.html .
+
+To add your project content to these guides, change the file
+`www/project-data/latest.yaml
+<http://git.openstack.org/cgit/openstack/openstack-manuals/tree/www/project-data/latest.yaml>`_
+in the openstack-manuals repository.
+
+For each repository, define the supported flags as explained in the
+`README.txt
+<http://git.openstack.org/cgit/openstack/openstack-manuals/tree/www/project-data/README.txt>`_
+.

doc/contributor-guide/source/project-guides.rst

@@ -2,8 +2,88 @@
 Project guide setup
 ===================
 
+OpenStack projects should follow the guidelines in this chapter for
+setting up their documentation structure to make it easy to find their
+documents and have consistency between OpenStack projects.
+
+To make it easy to include links from the landing pages on
+docs.openstack.org, we need to ensure a minimum level of consistency
+in the organization of the docs directory. The sections are based on
+high-level groupings that have evolved over the last years.
+
+Within each top-level directory, project teams are free to organize
+their content however seems most appropriate to them.
+
+This is the proposed layout for phase 1 (pike):
+
+* ``doc/source/``
+
+  * ``install/`` -- anything having to do with installation of the
+    project.
+  * ``contributor/`` -- anything related to contributing to the
+    project or how the team is managed. This applies to some of the previous
+    content under ``/developer``, the name is changed to emphasize
+    that not all contributors are developers and sometimes developers
+    are users but not contributors. Service projects should place
+    their automatically generated class documentation under this part
+    of the tree, for example in ``contributor/api`` or
+    ``contributor/internals``.
+  * ``configuration/`` -- automatically generated configuration
+    reference information based on oslo.config's sphinx integration
+    (or manually written for projects not using
+    oslo.config). Step-by-step guides for doing things like enabling
+    cells or configuring a specific driver should be placed in the
+    ``admin/`` section.
+  * ``cli/`` -- command line tool reference docs, similar to man pages.
+    These may be automatically generated with cliff's sphinx
+    integration, or manually written when auto-generation is not
+    possible. Tutorials or other step-by-step guides *using* these
+    tools should go in either the ``user/`` or ``admin/`` sections,
+    depending on their audience. Because the documentation for each
+    project should live in the repository with the code, this
+    directory may not be present for all service repositories but will
+    be present for most of the client library repositories.
+  * ``admin/`` -- any content from the old admin guide or anything
+    else that discusses how to run or operate the software. This
+    includes updating from one release to a newer version.
+  * ``user/`` -- end-user content such as concept guides, advice,
+    tutorials, step-by-step instructions for using the CLI to perform
+    specific tasks, etc.
+  * ``reference/`` -- any reference information associated with a
+    project that is not covered by one of the above categories.
+    Library projects should place their automatically generated class
+    documentation here.
+
+This layout is the *minimum* set. Projects are free and encouraged to
+add whatever other docs they need beyond this list, but these items
+are listed here explicitly because there are already links to most of
+them from landing pages, and landing pages can be created for the
+others.
+
+During a later phase, we will merge the API reference and release notes builds
+into the same job, along with the rest of the documentation for a project.
+Both of those builds have custom considerations, though, and it is more
+important to move the content that is no longer going to be maintained
+by the documentation team.
+
+* ``doc/source/``
+
+  * ``api/`` -- the REST API reference and guide content, when it exists.
+  * ``releasenotes/`` -- reno directions (the actual release notes
+    inputs will stay in /releasenotes/notes, where they are now).
+
+.. note::
+
+   Further discussion of the layout of the ``api/`` and
+   ``releasenotes/`` directories is deferred until we are further
+   along with the initial migration work. If you create content, feel
+   free to use these directories already as specified above.
+
+
+
 .. toctree::
    :maxdepth: 2
 
    project-install-guide.rst
    project-deploy-guide.rst
+   landing-pages.rst