@@ -1045,6 +1045,103 @@ subdirectory, but :file:`galleries/users_explain/artists` has a mix of
10451045any ``*.rst `` files to a ``:toctree: ``, either in the ``README.txt `` or in a
10461046manual ``index.rst ``.
10471047
1048+
1049+ .. _writing-user-guide :
1050+
1051+ Write user guide documentation
1052+ ==============================
1053+
1054+ The pages in the:ref: `users-guide-index ` are a mix of:ref: `ReST <writing-rest-pages >`
1055+ and:ref: `sphinx gallery <writing-examples-and-tutorials >` pages and should follow the
1056+ respective formatting conventions. The goal of the user guide is to explain how
1057+ Matplotlib works to someone who is unfamiliar with the library. To maintain the
1058+ consistency and cohesiveness of the user guide, documentation that is contributed to
1059+ this section should conform to the following guidelines:
1060+
1061+ Purpose: Explain how Matplotlib works
1062+ -------------------------------------
1063+
1064+ The aim of the user guide is to teach the conceptual abstractions on which the
1065+ Matplotlib API is developed so that users can understand how to fit the individual
1066+ components of the library together. Therefore, content should be concept oriented
1067+ rather than focused on specific tasks, e.g.
1068+
1069+ Lines in Matplotlib
1070+
1071+ rather than *How do I make a squiggly yellow line? *
1072+
1073+ Audience: new users
1074+ -------------------
1075+
1076+ The audience for the user guide are readers who are getting introduced to using Matplotlib
1077+ through the guide; therefore, the user guide should be written with the assumption that
1078+ the reader does not yet know what Matplotlib calls a given visualization task nor
1079+ how any task is accomplished in Matplotlib. For example, each document should first
1080+ introduce or define the object/module/concept that it is discussing and why it is
1081+ important for the reader. e.g.
1082+
1083+ The `~.Line2D ` class is an abstraction of a line and the ``LineCollection `` class is
1084+ an abstraction of a set of lines. ``Line2D `` and ``LineCollection `` objects manage
1085+ the properties and behavior of almost every line in an image. This means that one way
1086+ to modify a line is to call methods on its underlying object.*
1087+
1088+ As the user guide is intended to be read in a somewhat linear fashion, it should be
1089+ written with the assumption that the reader has read previous sections and cross
1090+ reference to those sections when it is critical that the reader has read those sections.
1091+
1092+
1093+ Scope: Visualization using Matplotlib
1094+ -------------------------------------
1095+
1096+ Many concepts in Matplotlib assume a grounding in visualization, statistics, and
1097+ other topics to understand how they work. These concepts should be
1098+ contextualized using common terminilogy, but the focus should not stray from the
1099+ Matplotlib topic, e.g.
1100+
1101+ ``Line2D `` objects take as input either pairwise coordinates (x,y) or y with an implicit
1102+ x. ``Line2D `` objects draw line segments between those points, thereby generating a
1103+ continuous representation.
1104+
1105+ Here *pairwise * and *continuous * are not defined because they are assumed to be known
1106+ by the audience, but the terms are used to explain what data ``Line2D `` accepts.
1107+
1108+
1109+ Strategy: Chunking and Scaffolding
1110+ ----------------------------------
1111+
1112+ When possible, the material is introduced in relatively small sections that build on top
1113+ of each other, which are teaching strategies called
1114+ `chunking and scaffolding <https://www.tacoma.uw.edu/digital-learning/chunking-scaffolding-pacing> `,
1115+ Chunking is aimed at reducing `cognitive load <https://carpentries.github.io/instructor-training/05-memory.html> `
1116+ by keeping the focus of each section relatively small, and scaffolding aims to show how
1117+ the concepts build on each other. The idea is to help the user develop a model of the
1118+ concept by first defining it and then layering on more information/functionality.
1119+
1120+ For example, here the line object is introduced, then there is one example of using a
1121+ method on the object, then the two concepts are combined, and then there is a link out
1122+ to further functionality::
1123+
1124+ For example, here the ``plot`` method returns a line object ``ln``::
1125+
1126+ ln, _ = plt.plot([1,2,3], color='blue')
1127+
1128+ One of the properties of a line is its color. It can be modified using the
1129+ ``set_color`` method of ``Line2D``::
1130+
1131+ ln.set_color('orange')
1132+
1133+ As shown in the figure below, the line color resulting from this modification is
1134+ orange:
1135+
1136+ ln, _ = plt.plot([1,2,3], color='blue')
1137+ ln.set_color('orange')
1138+
1139+ For a full list of methods see `~.Line2D`
1140+
1141+ For some examples, it may be preferable to take the inverse approach: start with
1142+ the combined example and then unpack it into its pieces.
1143+
1144+
10481145Miscellaneous
10491146=============
10501147