+As part of running ``tox``, two environments run: ``coala`` which does a variety
+of reStructuredText_ (and other) linting, and ``docs``, which runs Sphinx_ to
+build HTML and PDF documentation. You can run them independently by doing
+``tox -ecoala`` or ``tox -edocs``.
+
+The ``coala`` linter for reStructuredText is not always the most helpful in
+explaining why it failed. So, here are some common ones. There should also be
+Jenkins Failure Cause Management rules that will highlight these for you.
+
+Git Commit Message Errors
+"""""""""""""""""""""""""
+
+Coala checks that git commit messages adhere to the following rules:
+
+* Shortlog (1st line of commit message) is less than 50 characters
+* Shortlog (1st line of commit message) is in the imperative mood. For example,
+ "Add foo unit test" is good, but "Adding foo unit test is bad""
+* Body (all lines but 1st line of commit message) are less than 72 characters.
+ Some exceptions seem to exist, such as for long URLs.
+
+Some examples of those being logged are:
+
+::
+ Project wide:
+ | | [NORMAL] GitCommitBear:
+ | | Shortlog of HEAD commit isn't in imperative mood! Bad words are 'Adding'
+
+::
+ Project wide:
+ | | [NORMAL] GitCommitBear:
+ | | Body of HEAD commit contains too long lines. Commit body lines should not exceed 72 characters.
+
+Error in "code-block" directive
+"""""""""""""""""""""""""""""""
+
+If you see an error like this:
+
+::
+ docs/gerrit.rst
+ | 89| ···..·code-block::·bash
+ | | [MAJOR] RSTcheckBear:
+ | | (ERROR/3) Error in "code-block" directive:
+
+It means that the relevant code-block is not valid for the
+language specified, in this case ``bash``.
+
+.. note:: If you do not specify a language, the default language is Python. If
+ you want the code-block to not be an any particular language, instead
+ use the ``::`` directive. For example:
+
+::
+ ::
+ This is a code block
+ that will not be parsed
+ in any particluar langauge
+
+Project Documentation Requirements
+==================================
+
+Submitting Documentation Outlines (M2)
+--------------------------------------
+
+#. Determine the features your project will have and which ones will be
+ ''user-facing''.
+
+ * In general, a feature is user-facing if it creates functionality that a
+ user would directly interact with.
+ * For example, ``odl-openflowplugin-flow-services-ui`` is likely
+ user-facing since it installs user-facing OpenFlow features, while
+ ``odl-openflowplugin-flow-services`` is not because it provides only
+ developer-facing features.
+
+#. Determine pieces of documentation that you need to provide based on the
+ features your project will have and which ones will be user-facing.
+
+ * The kinds of required documentation can be found below in the
+ :ref:`requirements-for-projects` section.
+
+ .. note:: You might need to create multiple documents for the
+ same kind of documentation. For example, the controller project
+ will likely want to have a developer section for the config
+ subsystem as well as for the MD-SAL.
+
+#. Clone the docs repo: ``git clone https://git.opendaylight.org/gerrit/docs``
+#. For each piece of documentation find the corresponding template in the docs
+ repo.
+
+ * For user documentation: ``docs.git/docs/templates/template-user-guide.rst``
+ * For developer documentation: ``ddocs/templates/template-developer-guide.rst``
+ * For installation documentation (if any): ``docs/templates/template-install-guide.rst``
+
+ .. note:: You can find the rendered templates here:
+
+ .. toctree::
+ :maxdepth: 1
+
+ templates/template-user-guide
+ templates/template-developer-guide
+ templates/template-install-guide.rst
+
+
+#. Copy the template into the appropriate directory for your project.
+
+ * For user documentation: ``docs.git/docs/user-guide/${feature-name}-user-guide.rst``
+ * For developer documentation: ``docs.git/docs/developer-guide/${feature-name}-developer-guide.rst``
+ * For installation documentation (if any): ``docs.git/docs/getting-started-guide/project-specific-guides/${project-name}.rst``
+
+ .. note:: These naming conventions are not set in stone, but are used to
+ maintain a consistent document taxonomy. If these conventions
+ are not appropriate or do not make sense for a document
+ in development, use the convention that you think is more
+ appropriate and the documentation team will review it and give
+ feedback on the gerrit patch.
+
+#. Edit the template to fill in the outline of what you will provide using the
+ suggestions in the template. If you feel like a section is not needed, feel
+ free to omit it.
+
+#. Link the template into the appropriate core ``.rst`` file.
+
+ * For user documentation: ``docs.git/docs/user-guide/index.rst``
+ * For developer documentation: ``docs.git/docs/developer-guide/index.rst``
+ * For installation documentation (if any): ``docs.git/docs/getting-started-guide/project-specific-guides/index.rst``
+ * In each file, it should be pretty clear what line you need to add. In
+ general if you have an ``.rst`` file ``project-name.rst``, you include it
+ by adding a new line ``project-name`` without the ``.rst`` at the end.
+
+#. Make sure the documentation project still builds.
+
+ * Run ``tox`` from the root of the cloned docs repo.
+
+ * After that, you should be able to find the HTML version of the
+ docs at ``docs.git/docs/_build/html/index.html``.
+ * See :ref:`docs-rst` for more details about building the docs.
+
+ * The :ref:`reStructuredText Troubleshooting <docs-rst-troubleshooting>`
+ section provides common errors and solutions.
+ * If you still have problems e-mail the documentation group at
+ documentation@lists.opendaylight.org
+
+#. Commit and submit the patch.
+
+ #. Commit using:
+
+ .. code-block:: bash
+
+ git add --all && git commit -sm "Documentation outline for ${project-shortname}"
+
+ #. Submit using:
+
+ .. code-block:: bash
+
+ git review
+
+ See the `Git-review Workflow <https://wiki.opendaylight.org/view/Git-review_Workflow>`_
+ page if you don't have git-review installed.
+
+#. Wait for the patch to be merged or to get feedback
+
+ * If you get feedback, make the requested changes and resubmit the patch.
+ * When you resubmit the patch, it is helpful if you also post a "+0" reply to
+ the patch in Gerrit, stating what patch set you just submitted and what you
+ fixed in the patch set.
+
+Expected Output From Documentation Project
+------------------------------------------
+
+The expected output is (at least) 3 PDFs and equivalent web-based documentation:
+
+* User/Operator Guide
+* Developer Guide
+* Installation Guide
+
+These guides will consist of "front matter" produced by the documentation group
+and the per-project/per-feature documentation provided by the projects.
+
+.. note:: This requirement is intended for the person responsible for the
+ documentation and should not be interpreted as preventing people not
+ normally in the documentation group from helping with front matter
+ nor preventing people from the documentation group from helping with
+ per-project/per-feature documentation.
+
+Project Documentation Requirements
+----------------------------------
+
+.. _kinds-of-docs:
+
+Content Types
+^^^^^^^^^^^^^
+
+These are the expected kinds of documentation and target audiences for each
+kind.
+
+* **User/Operator:** for people looking to use the feature without writing code
+
+ * Should include an overview of the project/feature
+ * Should include description of availble configuration options and what they
+ do
+
+* **Developer:** for people looking to use the feature in code without modifying
+ it
+
+ * Should include API documentation, such as, enunciate for REST, Javadoc for
+ Java, ??? for RESTCONF/models
+
+* **Contributor:** for people looking to extend or modify the feature's source
+ code
+
+ .. note:: You can find this information on the wiki.
+
+* **Installation:** for people looking for instructions to install the feature
+ after they have downloaded the ODL release
+
+ .. note:: The audience for this content is the same as User/Operator docs
+
+ * For most projects, this will be just a list of top-level features and
+ options
+
+ * As an example, l2switch-switch as the top-level feature with the -rest
+ and -ui options
+ * Features should also note if the options should be checkboxes (that is,
+ they can each be turned on/off independently) or a drop down (that is, at
+ most one can be selected)
+ * What other top-level features in the release are incompatible with each
+ feature
+ * This will likely be presented as a table in the documentation and the
+ data will likely also be consumed by automated
+ installers/configurators/downloaders
+
+ * For some projects, there is extra installation instructions (for external
+ components) and/or configuration
+
+ * In that case, there will be a (sub)section in the documentation
+ describing this process.
+
+* **HowTo/Tutorial:** walk throughs and examples that are not general-purpose
+ documentation
+
+ * Generally, these should be done as a (sub)section of either user/operator
+ or developer documentation.
+ * If they are especially long or complex, they may belong on their own
+
+* **Release Notes:**
+
+ * Release notes are required as part of each project's release review. They
+ must also be translated into reStructuredText for inclusion in the formal
+ documentation.
+
+.. _requirements-for-projects:
+
+Requirements for projects
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Projects must provide reStructuredText documentation including: