1 files changed, 63 insertions, 0 deletions
diff --git a/doc/source/dev/howto-docs.rst b/doc/source/dev/howto-docs.rst
index 9354357e8..3156d3452 100644
--- a/doc/source/dev/howto-docs.rst
+++ b/doc/source/dev/howto-docs.rst
@@ -153,6 +153,69 @@ if you write a tutorial on your blog, create a YouTube video, or answer question
 on Stack Overflow and other sites.
 
 
+.. _howto-document:
+
+*******************
+Documentation style
+*******************
+
+.. _userdoc_guide:
+
+User documentation
+==================
+
+- In general, we follow the
+  `Google developer documentation style guide <https://developers.google.com/style>`_
+  for the User Guide.
+
+- NumPy style governs cases where:
+
+      - Google has no guidance, or
+      - We prefer not to use the Google style
+
+  Our current rules:
+
+      - We pluralize *index* as *indices* rather than
+        `indexes <https://developers.google.com/style/word-list#letter-i>`_,
+        following the precedent of :func:`numpy.indices`.
+
+      - For consistency we also pluralize *matrix* as *matrices*.
+
+- Grammatical issues inadequately addressed by the NumPy or Google rules are
+  decided by the section on "Grammar and Usage" in the most recent edition of
+  the `Chicago Manual of Style
+  <https://en.wikipedia.org/wiki/The_Chicago_Manual_of_Style>`_.
+
+- We welcome being
+  `alerted <https://github.com/numpy/numpy/issues>`_ to cases
+  we should add to the NumPy style rules.
+
+.. _docstring_intro:
+
+Docstrings
+==========
+
+When using `Sphinx <http://www.sphinx-doc.org/>`_ in combination with the
+NumPy conventions, you should use the ``numpydoc`` extension so that your
+docstrings will be handled correctly. For example, Sphinx will extract the
+``Parameters`` section from your docstring and convert it into a field
+list.  Using ``numpydoc`` will also avoid the reStructuredText errors produced
+by plain Sphinx when it encounters NumPy docstring conventions like
+section headers (e.g. ``-------------``) that sphinx does not expect to
+find in docstrings.
+
+It is available from:
+
+* `numpydoc on PyPI <https://pypi.python.org/pypi/numpydoc>`_
+* `numpydoc on GitHub <https://github.com/numpy/numpydoc/>`_
+
+Note that for documentation within NumPy, it is not necessary to do
+``import numpy as np`` at the beginning of an example.
+
+Please use the ``numpydoc`` :ref:`formatting standard <numpydoc:format>` as
+shown in their :ref:`example <numpydoc:example>`.
+
+
 *********************
 Documentation reading
 *********************