matplotlib
diff --git a/‎doc/devel/documenting_mpl.rst
Lines changed: 28 additions & 28 deletions b/‎doc/devel/documenting_mpl.rst
Lines changed: 28 additions & 28 deletions
@@ -1,8 +1,8 @@
 .. _documenting-matplotlib:
 
-===========================================
-Developer's tips for documenting Matplotlib
-===========================================
 ================================
+Developer's tips for documenting
+================================
 
 Getting started
 ===============
@@ -54,7 +54,7 @@ Building the docs
 
 The documentation sources are found in the :file:`doc/` directory in
 the trunk.  To build the documentation in html format, cd into
-:file:`doc/` and run::
+:file:`doc/` and run:
 
 .. code-block:: sh
 
@@ -72,16 +72,15 @@ The list of comamnds and flags for ``make.py`` can be listed by running
   many warnings at once.
 
 
-Organization of Matplotlib's documentation
-==========================================
+Documentation organization
+==========================
 
 The actual reStructured Text files are kept in :file:`doc/users`,
 :file:`doc/devel`, :file:`doc/api` and :file:`doc/faq`. The main entry point is
 :file:`doc/index.rst`, which pulls in the :file:`index.rst` file for the users
 guide, developers guide, api reference, and FAQs. The documentation suite is
 built as a single document in order to make the most effective use of cross
-referencing (we want to make navigating the Matplotlib documentation as easy as
-possible).
+referencing.
 
 Additional files can be added to the various guides by including their base
 file name (the .rst extension is not necessary) in the table of contents.
@@ -95,11 +94,14 @@ statement, such as::
 Formatting
 ==========
 
-All new or edited docstrings should conform to the numpydoc guidelines. These
-split the docstring down into a number of sections - see
+Most documentaiton lives in "docstrings". These are comment blocks in the source
+code that explain how the code works. All new or edited docstrings should
+conform to the numpydoc guidelines. These split the docstring into a number
+of sections - see
 https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt for more
-details and a guide to the way docstrings should be written. A simple example
-docstring looks like:
+details and a guide to how docstrings should be formatted.
+
+An example docstring looks like:
 
 .. code-block:: python
 
@@ -142,8 +144,8 @@ working with Sphinx in general.
 
 Function arguments
 ------------------
-Function arguments and keywords should be referred to using the
-``*emphasis*`` role. This will keep Matplotlib's documentation consistent
+Function arguments and keywords within docstrings should be referred to using
+the ``*emphasis*`` role. This will keep Matplotlib's documentation consistent
 with Python's documentation:
 
 .. code-block:: rst
@@ -221,26 +223,26 @@ Figures
 Dynamically generated figures
 -----------------------------
 
-Figures can be automatically generated from scripts and included in
-the docs.  It is not necessary to explicitly save the figure in the
-script, this will be done automatically at build time to ensure that
-the code that is included runs and produces the advertised figure.
+Figures can be automatically generated from scripts and included in the docs.
+It is not necessary to explicitly save the figure from the script; this will be
+done automatically when the docs are built to ensure that the code that is
+included runs and produces the advertised figure.
 
-The path should be relative to the ``doc`` directory.  Any plots
-specific to the documentation should be added to the ``doc/mpl_examples/pyplots``
-directory and committed to git.  Plots from the ``examples`` directory
-may be referenced through the symlink ``mpl_examples`` in the ``doc``
-directory, e.g.:
+Plotting code should be added to the :file:`examples` directory.  Plots from
+the :file:`examples` directory may be referenced through the symlink
+``mpl_examples`` in the ``doc`` directory, e.g.:
 
 .. code-block:: rst
 
-  .. plot:: mpl_examples/pylab_examples/simple_plot.py
+  .. plot:: mpl_examples/lines_bars_and_markers/fill.py
 
 The ``:scale:`` directive rescales the image to some percentage of the
 original size, though we don't recommend using this in most cases
 since it is probably better to choose the correct figure size and dpi
 in Matplotlib and let it handle the scaling.
 
+To include plots in docstrings, see the following guide:
+
 Plot directive documentation
 ''''''''''''''''''''''''''''
 
@@ -250,10 +252,8 @@ Examples
 --------
 
 The source of the files in the ``examples`` directory are
-automatically included in the HTML docs.  An image is generated and
-included for all examples in the ``api`` and ``pylab_examples``
-directories.  To exclude the example from having an image rendered,
-insert the following special comment anywhere in the script:
+automatically included in the HTML docs. To exclude the example from having an
+image rendered, insert the following special comment anywhere in the script:
 
 .. code-block:: python