From 7c34ce5d6930e592b098606644c32df42ca38d15 Mon Sep 17 00:00:00 2001 From: Lana Brindley Date: Mon, 14 Mar 2016 14:25:44 +1000 Subject: [PATCH] Reorganised Quickstart chapter Reorganised to add quickstart info for developers and new big tent projects. Change-Id: I698a49ff1628349d372f91136b2829be5f8c2ebc Closes-Bug: #1553873 Depends-On: I72a7d57ae49ed2123475d3d1051c630e7b69dcaf --- doc/contributor-guide/source/doc-bugs.rst | 2 +- doc/contributor-guide/source/index.rst | 2 +- doc/contributor-guide/source/quickstart.rst | 17 +++++++++++ .../source/quickstart/developers.rst | 15 ++++++++++ .../first-timers.rst} | 11 ++++--- .../source/quickstart/new-projects.rst | 29 +++++++++++++++++++ 6 files changed, 68 insertions(+), 8 deletions(-) create mode 100644 doc/contributor-guide/source/quickstart.rst create mode 100644 doc/contributor-guide/source/quickstart/developers.rst rename doc/contributor-guide/source/{first-timers-quickstart.rst => quickstart/first-timers.rst} (99%) create mode 100644 doc/contributor-guide/source/quickstart/new-projects.rst diff --git a/doc/contributor-guide/source/doc-bugs.rst b/doc/contributor-guide/source/doc-bugs.rst index 8495d5a258..d45de4b97f 100644 --- a/doc/contributor-guide/source/doc-bugs.rst +++ b/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 diff --git a/doc/contributor-guide/source/index.rst b/doc/contributor-guide/source/index.rst index ba424f4bc6..a3ccb6e9e1 100644 --- a/doc/contributor-guide/source/index.rst +++ b/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 diff --git a/doc/contributor-guide/source/quickstart.rst b/doc/contributor-guide/source/quickstart.rst new file mode 100644 index 0000000000..6dd1cdc02e --- /dev/null +++ b/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 diff --git a/doc/contributor-guide/source/quickstart/developers.rst b/doc/contributor-guide/source/quickstart/developers.rst new file mode 100644 index 0000000000..c762f9ec46 --- /dev/null +++ b/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. diff --git a/doc/contributor-guide/source/first-timers-quickstart.rst b/doc/contributor-guide/source/quickstart/first-timers.rst similarity index 99% rename from doc/contributor-guide/source/first-timers-quickstart.rst rename to doc/contributor-guide/source/quickstart/first-timers.rst index cbf8faf007..6e1d7f4441 100644 --- a/doc/contributor-guide/source/first-timers-quickstart.rst +++ b/doc/contributor-guide/source/quickstart/first-timers.rst @@ -1,9 +1,8 @@ +.. _first_timers: -.. _first_timers_quickstart: - -========== -Quickstart -========== +============ +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. @@ -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: diff --git a/doc/contributor-guide/source/quickstart/new-projects.rst b/doc/contributor-guide/source/quickstart/new-projects.rst new file mode 100644 index 0000000000..7b91149f6f --- /dev/null +++ b/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.