content guidelines

story645 · story645 · commit 08c78bab6bfa · 2023-07-26T15:40:20.000-04:00
diff --git a/doc/devel/document.rst b/doc/devel/document.rst
@@ -1002,6 +1002,79 @@ 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 explanations
+=============================
+
+The pages in the user guide 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. These pages are also intended 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 to use Matplotlib
+--------------------------------------
+
+The aim of this guide is to teach the concepts of Matplotlib so that user 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. *What is a `Line2D` artist?* rather than *How do I make a yellow
+squiggly line?*
+
+
+Scope: Matplotlib objects and modules
+-------------------------------------
+
+Many concepts in Matplotlib assume a grounding in visualization, statistics, and
+other topics to understand how they work. These concepts should be
+contextualized using common terminilogy, but the focus should not stray from the
+Matplotlib topic, e.g. *`Line2D` objects take as input either pairwise coordinates
+(x,y) or y with an implicit x and assume that the input data is continuous.*
+Here pairwise and continuous are not defined because they are assumed to be
+known by the audience, but are used to explain what data ``Line2D`` accepts.
+
+
+Audience: new users
+-------------------
+
+The audience for this guide is getting introduced to using Matplotlib through
+this guide. Therefore content should be written with the assumption that the
+reader does not yet know what Matplotlib calls a given visualization task or
+how any task is accomplished in Matplotlib. Therefore each document should
+always first introduce or define the object/module/concept that it is discussing
+and why it is important for the reader. e.g. *The ``Line2`` 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.*
+
+
+Teaching style: small chunks
+----------------------------
+
+The material is introduced in small, usually one change or task at a time,
+chunks to keep focus on the specific line of code enabling the given task. The
+aim is that this breakdown will help in understanding what each specific object
+does and build intuition in how the objects behave that will make the docs
+easier to read. For example, here the line object is introduced, then there is
+one example of using a method on the object, 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])
+
+  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')
+
+  For a full list of methods see `~.Line2D`
+
+
 Miscellaneous
 =============
 
