Document formatting strings in the docs

timhoffm · timhoffm · commit 79c1c568a19c · 2019-10-04T12:08:54.000+02:00
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,10 @@ Use simple single or double quotes when giving string values, e.g.
 
   If 'tight', try to figure out the tight bbox of the figure.
 
+The ues of extra literal quotes around the text (````'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
