content guidelines

story645 · story645 · commit a69b4ae42d0c · 2023-12-23T18:22:46.000-05:00
diff --git a/doc/devel/document.rst b/doc/devel/document.rst
@@ -1045,6 +1045,104 @@ subdirectory, but  :file:`galleries/users_explain/artists` has a mix of
 any ``*.rst`` files to a ``:toctree:``, either in the ``README.txt`` or in a
 manual ``index.rst``.
 
+
+.. _writing-user-guide:
+
+Write user guide documentation
+==============================
+
+The pages in the :ref:`users-guide-index` are a mix of :ref:`ReST <writing-rest-pages>`
+and :ref:`sphinx gallery <writing-examples-and-tutorials>` pages and should follow the
+respective formatting conventions. The goal of the user guide is to explain how
+Matplotlib works to someone who is unfamiliar with the library. To maintain the
+consistency and cohesiveness of the user guide, documentation that is contributed to
+this section should conform to the following guidelines:
+
+Purpose: Explain how Matplotlib works
+-------------------------------------
+
+The aim of the user guide is to teach the conceptual abstractions on which the
+Matplotlib API is developed so that users can understand how to fit the individual
+components of the library together. Therefore, content should be concept oriented
+rather than focused on specific tasks, e.g.
+
+  Lines in Matplotlib
+
+rather than *How do I make a squiggly yellow line?*
+
+Audience: new Matplotlib users
+------------------------------
+
+The audience for the user guide are readers who are getting introduced to using Matplotlib
+through the guide; therefore, the user guide should be written with the assumption that
+the reader does not yet know what Matplotlib calls a given visualization task nor
+how any task is accomplished in Matplotlib. For example, each document should first
+introduce or define the object/module/concept that it is discussing and why it is
+important for the reader. e.g.
+
+  The `~.Line2D` class is an abstraction of a line and the ``LineCollection`` class is
+  an abstraction of a set of lines. ``Line2D`` and ``LineCollection`` objects manage
+  the properties and behavior of almost every line in an image. This means that one way
+  to modify a line is to call methods on its underlying object.*
+
+As the user guide is intended to be read in a somewhat linear fashion, it should be
+written with the assumption that the reader has read previous sections and cross
+reference to those sections when it is critical that the reader has read those sections.
+
+
+Scope: Visualization using Matplotlib
+-------------------------------------
+
+Many concepts in Matplotlib assume a grounding in visualization, statistics, Python
+programming, and other topics to understand how they work. These concepts should be
+contextualized using common terminology, but the focus should not stray from the
+Matplotlib topic, e.g.
+
+  ``Line2D`` objects take as input a list of pairwise coordinates (x,y) and generates
+  line segments connecting each pair of points with the next pair in the list.
+
+Here *pairwise coordinates* are not defined because it is a common term from math and
+therefore defining it is out of scope. For some terms, it may also be appropriate to
+link out to an explanation.
+
+Strategy: Chunking and Scaffolding
+----------------------------------
+
+When possible, the material is introduced in tightly scoped sections that build on top
+of each other, using teaching strategies called `chunking and scaffolding`_.
+Chunking is aimed at reducing `cognitive load`_ by keeping the focus of each section
+relatively small, and scaffolding lays out instructional material such that each section
+builds on the previous one. The idea is to help the user develop a model of the concept
+by first defining it and then illustrating how that understanding facilitates better use
+of the library.
+
+For example, here the line object is introduced, then there is one example of using a
+method on the object. This primes the reader to better understand the example where the
+two concepts are combined, and then there is a link out to further functionality::
+
+  For example, here the ``plot`` method returns a line object ``ln``::
+
+    ln, _ = plt.plot([1,2,3], color='blue')
+
+  One of the properties of a line is its color. It can be modified using the
+  ``set_color`` method of ``Line2D``::
+
+    ln.set_color('orange')
+
+  As shown in the figure below, the line color resulting from this modification is
+  orange:
+
+    ln, _ = plt.plot([1,2,3], color='blue')
+    ln.set_color('orange')
+
+  For a full list of methods see `~.Line2D`
+
+For some examples, it may be preferable to take the inverse approach: start with
+the combined example and then unpack it into its pieces.
+
+.. _`chunking and scaffolding`: https://www.tacoma.uw.edu/digital-learning/chunking-scaffolding-pacing
+.. _`cognitive load`: https://carpentries.github.io/instructor-training/05-memory.html
+
 Miscellaneous
 =============
 
