Document instructions for documentation

A lot of things have been changing with OpenStack's
documentation. As a community, we could do a better
job at catching up with these changes and
documenting our project well enough for the
benefit of all stakeholders.

Add instructions on where to document what and
provide tips to manila developers on documentation.

Change-Id: I660bfd5ac3d61c253e1e7b4b02c51424a03fa0a0
Partially-implements: bp improve-manila-developer-docs

doc/source/devref/adding_release_notes.rst

@@ -1,3 +1,5 @@
+.. _adding_release_notes:
+
 Release Notes
 =============
 

doc/source/devref/commit_message_tags.rst

@@ -1,3 +1,5 @@
+.. _commit_message_tags:
+
 Using Commit Message Tags in Manila
 ===================================
 
@@ -22,6 +24,8 @@ placed on a separate line. The following tags are used in manila.
   updates to documentation in order to be understood. This tag can also be
   used if the documentation is provided along with the patch itself. This will
   also generate a Launchpad bug in manila for triaging and tracking.
+  Refer to the section on :ref:`documenting_your_work` to understand where
+  to add documentation.
 - **Implements: | Partially Implements:** *blueprint <name_of_blueprint>* - Use
   this tag when a change implements or partially implements the given blueprint
   in Launchpad. This will automatically generate a link to the blueprint in

doc/source/devref/documenting_your_work.rst

@@ -0,0 +1,209 @@
+.. _documenting_your_work:
+
+=====================
+Documenting your work
+=====================
+
+
+As with most OpenStack services and libraries, manila suffers from appearing
+very complicated to understand, develop, deploy, administer and use. As
+OpenStack developers working on manila, our responsibility goes beyond
+introducing new features and maintaining existing features. We ought to
+provide adequate documentation for the benefit of all kinds of audiences. The
+guidelines below will explain how you can document (or maintain
+documentation for) new (or existing) features and bug fixes in the core manila
+project and other projects that are part of the manila suite.
+
+
+Where to add documentation?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+OpenStack User Guide
+--------------------
+- Any documentation targeted at end users of manila in OpenStack needs to go
+  here. This contains high level information about any feature as long as it
+  is available on ``python-manilaclient`` and/or ``manila-ui``.
+- If you develop an end user facing feature, you need to provide an
+  overview, use cases and example work-flows as part of this documentation.
+- **Link**: `User guide <http://docs.openstack.org/user-guide/>`_
+- **Repository**: The user guide is maintained within the
+  `OpenStack Manuals project <https://github.com/openstack/openstack-manuals>`_
+
+
+OpenStack Administrator Guide
+-----------------------------
+- Documentation for administrators of manila deployments in OpenStack clouds
+  needs to go here.
+- Document instructions for administrators to perform necessary set up
+  for utilizing a feature, along with managing and troubleshooting manila
+  when the feature is used.
+- Relevant configuration options may be mentioned here briefly.
+- **Link**: `Administrator guide <http://docs.openstack.org/admin-guide/>`_
+- **Repository**: The administrator guide is maintained within the
+  `OpenStack Manuals project <https://github.com/openstack/openstack-manuals>`_
+
+
+OpenStack Configuration Reference
+---------------------------------
+- Instructions regarding configuration of different manila back ends need to
+  be added in this document.
+- The configuration reference also contains sections where manila's
+  configuration options are auto-documented.
+- It contains sample configuration files for using manila with various
+  configuration options.
+- If you are a driver maintainer, please ensure that your driver and all of
+  its relevant configuration is documented here.
+- **Link**: `Mitaka release configuration reference
+  <http://docs.openstack.org/mitaka/config-reference/>`_
+- **Repository**: The configuration reference is maintained within the
+  `OpenStack Manuals project <https://github.com/openstack/openstack-manuals>`_
+
+
+OpenStack Installation Guide
+----------------------------
+- Instructions regarding setting up manila on OpenStack need to be documented
+  here.
+- This guide covers step-by-step deployment of OpenStack services using a
+  functional example architecture suitable for new users of OpenStack with
+  sufficient Linux experience.
+- The instructions are written together, but with the help of tags are
+  separated out into per-distro installation guides for hosting on the
+  documentation website.
+- The installation instructions for manila in the Mitaka release lived
+  alongside the major projects in the installation guide. However, with the
+  Newton release, the install guide will be part of manila's code tree.
+- **Links**:
+
+  - `Mitaka installation guide for openSUSE and SLES
+    <http://docs.openstack.org/mitaka/install-guide-obs/>`_
+  - `Mitaka installation guide for Red Hat Enterprise Linux and CentOS
+    <http://docs.openstack.org/mitaka/install-guide-rdo/>`_
+  - `Mitaka installation guide for Ubuntu 14.04
+    <http://docs.openstack.org/mitaka/install-guide-ubuntu/>`_
+
+- **Repository**: The installation guide is maintained within the
+  `OpenStack Manuals project
+  <https://github.com/openstack/openstack-manuals>`_. However, with the
+  Newton release, manila's install guide will live in its project tree.
+
+.. TODO(gouthamr): add actual links and repo instructions when available.
+
+
+OpenStack API Reference
+-----------------------
+- When you add or change a REST API in manila, you will need to add or edit
+  descriptions of the API, request and response parameters, microversions and
+  expected HTTP response codes as part of the API reference.
+- For releases prior to Newton, the API reference was maintained in `Web
+  Application Description Language (WADL)
+  <https://en.wikipedia.org/wiki/Web_Application_Description_Language>`_
+- Starting with the Newton release, manila's API reference will be maintained
+  in-tree in custom YAML/JSON format files.
+- **Links**:
+
+  - `REST API reference of the Shared File Systems Project v1.0
+    <http://developer.openstack.org/api-ref-share-v1.html>`_
+  - `REST API reference of the Shared File Systems Project v2.0
+    <http://developer.openstack.org/api-ref-share-v2.html>`_
+
+- **Repository**: The API reference is maintained within the
+  `OpenStack API Site repository
+  <https://github.com/openstack/api-site>`_. However, with the Newton release,
+  manila's API reference will live in its project tree.
+
+.. TODO(gouthamr): add actual links and repo instructions when available.
+
+
+Manila Developer Reference
+--------------------------
+- When working on a feature in manila, provide judicious inline documentation
+  in the form of comments and docstrings. Code is our best developer reference.
+- Driver entry-points must be documented with docstrings explaining the
+  expected behavior from a driver routine.
+- Apart from inline documentation, further developer facing documentation
+  will be necessary when you are introducing changes that will affect vendor
+  drivers, consumers of the manila database and when building a utility in
+  manila that can be consumed by other developers.
+- The developer reference for manila is maintained in-tree.
+- Feel free to use it as a sandbox for other documentation that does not
+  live in manila's code-tree.
+- **Link**: `Manila developer reference
+  <http://docs.openstack.org/developer/manila/>`_
+
+
+OpenStack Security Guide
+-------------------------
+- Any feature that has a security impact needs to be documented here.
+- In general, administrators will follow the guidelines regarding best
+  practices of setting up their manila deployments with this guide.
+- Any changes to ``policy.json`` based authorization, share network related
+  security, ``access`` to manila resources, tenant and user related
+  information needs to be documented here.
+- **Link**: `Security guide <http://docs.openstack.org/security-guide/>`_
+- **Repository**: The security guide is maintained within the
+  `OpenStack Security-doc project <https://github.com/openstack/security-doc>`_
+
+
+OpenStack Command Line Reference
+--------------------------------
+- Help text provided in the ``python-manilaclient`` is extracted into this
+  document automatically.
+- No manual corrections are allowed on this repository; make necessary
+  corrections in the ``python-manilaclient`` repository."
+- **Link**: `Manila CLI reference
+  <http://docs.openstack.org/cli-reference/manila.html>`_
+- **Repository**: The CLI reference is maintained within the
+  `OpenStack Manuals project
+  <https://github.com/openstack/openstack-manuals>`_.
+
+
+Important things to note
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+- When implementing a new feature, use appropriate
+  Commit Message Tags (:ref:`commit_message_tags`).
+- Using the ``DocImpact`` flag in particular will create a ``[doc]`` bug
+  under the `manila project in launchpad
+  <https://bugs.launchpad.net/manila>`_. When your code patch merges, assign
+  this bug to yourself and track your documentation changes with it.
+- When writing documentation outside of manila, use either a commit message
+  header that includes the word ``Manila`` or set the topic of the
+  change-set to ``manila-docs``. This will make it easy for manila reviewers
+  to find your patches to aid with a technical content review.
+- When writing documentation in user/admin/config/api/install guides,
+  *always* refer to the project with its service name: ``Shared File Systems
+  service`` and not the service type (``share``) or the project name
+  (``manila``).
+- Follow documentation styles prescribed in the `OpenStack Documentation
+  Contributor Guide <http://docs.openstack.org/contributor-guide/>`_. Pay
+  heed to the `RST formatting conventions
+  <http://docs.openstack.org/contributor-guide/rst-conv.html>`_
+  and `Writing style
+  <http://docs.openstack.org/contributor-guide/writing-style.html>`_.
+- Use CamelCase to spell out `OpenStack` and sentence casing to
+  spell out service types, ex: `Shared File Systems service` and lower case
+  to spell out project names, ex: `manila` (except when the project name is in
+  the beginning of a sentence or a title).
+- **ALWAYS** use a first party driver when documenting a feature in the user
+  or administrator guides. Provide cross-references to configuration
+  reference sections to lead readers to detailed setup instructions for
+  these drivers.
+- The manila developer reference, the OpenStack user guide, administrator
+  reference, API reference and security guide are always *current*, i.e, get
+  built with every commit in the respective codebase. Therefore, documentation
+  added here need not be backported to previous releases.
+- You may backport changes to some documentation such as the configuration
+  reference and the installation guide. Refer to the instructions `here
+  <http://docs.openstack.org/contributor-guide/additional-git-workflow/
+  backport.html>`_.
+- **Important "documentation" that isn't really documentation** - ``specs`` and
+  ``release notes`` are *NOT* documentation. A specification document is
+  written to initiate a dialogue and gather feedback regarding the
+  design of a feature. Neither developers nor users will regard a
+  specification document as official documentation after a feature has been
+  implemented. Release notes (:ref:`adding_release_notes`) allow for
+  gathering release summaries and they are not used to understand,
+  configure, use or troubleshoot any manila feature.
+- **Less is not more, more is more** - Always add detail when possible. The
+  health and maturity of our community is reflected in our documentation.

doc/source/devref/index.rst

@@ -29,6 +29,7 @@ Programming HowTos and Tutorials
     development.environment
     unit_tests
     addmethod.openstackapi
+    documenting_your_work
     adding_release_notes
     commit_message_tags