Merge "Reorganised Quickstart chapter"

doc/contributor-guide/source/doc-bugs.rst

@@ -24,7 +24,7 @@ Bugs differ depending on:
 .. note::
 
    To work on documentation bugs, join the openstack-doc-bugs team on
-   Launchpad. For more information, see :ref:`first_timers_quickstart`.
+   Launchpad. For more information, see :ref:`first_timers`.
 
 Go through the triaging process and look for possible duplicate bugs
 before working on a bug. Do not work on a documentation bug until it is set to

doc/contributor-guide/source/index.rst

@@ -16,7 +16,7 @@ Contents
 .. toctree::
    :maxdepth: 2
 
-   first-timers-quickstart.rst
+   quickstart.rst
    additional-git-workflow.rst
    writing-style.rst
    topic-structure.rst

doc/contributor-guide/source/quickstart.rst

@@ -0,0 +1,17 @@
+.. _quickstart:
+
+==========
+Quickstart
+==========
+
+There are several reasons why you might consider contributing to OpenStack
+documentation. This chapter addresses the main reasons why you might
+contribute, and gives specific information about how to get started in each
+use case.
+
+.. toctree::
+   :maxdepth: 2
+
+   quickstart/first-timers.rst
+   quickstart/developers.rst
+   quickstart/new-projects.rst

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

@@ -0,0 +1,15 @@
+.. _developers:
+
+==========
+Developers
+==========
+
+When you are writing a new feature for a component of OpenStack, it is
+important that you also document that new feature. This is also true if you
+are adding or changing configuration options, commands, or other user-
+facing components.
+
+Many of these types of changes are handled automatically by
+`openstack-doc-tools`, and published to the Configuration Reference
+and Command Line Reference Guides. For more information about these automated
+tools, see the :ref:`doc-tools` chapter.

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

@@ -1,9 +1,8 @@
+.. _first_timers:
 
-.. _first_timers_quickstart:
+============
-
+First timers
-==========
+============
-Quickstart
-==========
 
 One of the best ways to start contributing to OpenStack documentation
 is to walk through the Installation guide and complete it by hand.
@@ -25,7 +24,7 @@ Other good first-time documentation tasks are bug triaging and bug fixing:
 
 The following diagram shows the basic setup workflow:
 
-.. image:: figures/workflow-diagram.png
+.. image:: ../figures/workflow-diagram.png
       :alt: Workflow diagram
 
 .. _setting_up_for_contribution:

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

@@ -0,0 +1,29 @@
+.. _new_projects:
+
+============
+New projects
+============
+
+If you are maintaining a new project that has recently been accepted into the
+OpenStack 'big tent' then you will require some documentation for your
+project.
+
+Developer documentation for your project should live in your project's git
+repository, and be published to `docs.openstack.org/developer/yourproject`.
+If you need to create that index page, send a patch to the openstack-manuals
+team. You will also need to add the `openstack-server-publish` job to the
+appropriate repositories so that the index page is re-published with every
+commit.
+
+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.