Backport PR #15379: Document formatting strings in the docs

dstansby · MeeseeksDev[bot] · commit 1a22ba1452a6 · 2019-10-07T12:27:45.000Z
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -390,7 +390,7 @@ consistent with Python's documentation:
 
 .. code-block:: rst
 
-  If *linestyles* is *None*, the 'solid' is used.
+  If *linestyles* is *None*, the default is 'solid'.
 
 Do not use the ```default role``` or the ````literal```` role:
 
@@ -410,6 +410,12 @@ Use simple single or double quotes when giving string values, e.g.
 
   If 'tight', try to figure out the tight bbox of the figure.
 
+  No ``'extra'`` literal quotes.
+
+The use of extra literal quotes around the text is discouraged. While they
+slightly improve the rendered docs, they are cumbersome to type and difficult
+to read in plain-text docs.
+
 Parameter type descriptions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The main goal for parameter type descriptions is to be readable and
