.. _documenting-content:

Content guidelines

The following content guidelines aim to improve the consistency, cohesiveness, and

organization of the documentation on using the library. Broadly, this documentations

falls into one of these sections:

:ref:`plot_types`

Summary of visualization techniques implemented as high-level API

:ref:`users-guide-explain`

:ref:`tutorials`

:ref:`examples-index`

:ref:`api-reference`

Descriptions of the public modules, objects, methods, and functions.

.. _content-plot-types:

Plot types gallery

The plot type gallery displays a selection of the common visualization techniques that

are implemented in Matplotlib. The gallery is heavily curated and tightly scoped to the

plotting methods on `matplotlib.axes.Axes` so additions are generally discouraged.

Format

* very short: 5-10 lines

* self explanatory data

* little to no customization.

.. _content-user-guide:

User guide

The goal of the user guide is to explain how Matplotlib works to someone who is

unfamiliar with the library. The focus is primarily on the functionality provided by the

library.

Purpose

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

The Matplotlib audience encompasses a wide spectrum of users, from readers who are first

getting introduced to using Matplotlib through the guide to experienced developers who

want to make something extremely customizied. Instead of trying to write for the

spectrum, documents should identify their audience so the reader can asses whether the

document is appropriate for them.

For example, introductory documents 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. Those documents 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.*

Documents that assume familarity with the library should, when possible, be explicit

about what knowledge the audience is assumed to have, e.g.

This guide assumes that the user understands the general concept of Artists, as

explained in:doc:`../users/explain/artists/artist_intro`

Generally the user guide should be written with the assumption that the reader has

read previous sections and documents should cross reference as necessary rather than

duplicating information.

Scope

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 for all documents 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.

Format

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.

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 some examples, it may be preferable to take the inverse approach: start with

the combined example and then unpack it into its pieces.

In general, this approach is aimed at helping the user develop a model of the concept

by first defining it and then illustrating how that understanding facilitates better use

of the library. In keeping with this goal, documents should also be tightly focused on

one topic and link out to related material, e.g. linking to the `.Axes.plot`

documentation rather then explaining it here.

.. _`chunking and scaffolding`:https://www.tacoma.uw.edu/digital-learning/chunking-scaffolding-pacing

.. _`cognitive load`:https://carpentries.github.io/instructor-training/05-memory.html

.. _content-tutorials:

Tutorials

The goal of the tutorials is to teach the reader how to use Matplotlib to build a

specific complex visualization. As opposed to the user guide where the functionality

takes focus, in the tutorials the goal takes center stage.

Format

As with the user guide, the tutorials should aim to unpack information in chunks and

build on the previous section. As demonstrated, here it is used to walk with the user

through the steps involved in animating a line plot. Generally the content is limited

to describing what is happening at each stage- for example there's no explanation of

why an update function is written-and instead the reader is linked to explanation.

For example, where the user guide explains ``Line2D``, a tutorial on animating

a sin wave would instruct the reader on setting the new location, eg::

Also note that while the aim is to show how to animate a sin curve, the focus is always

on making the animation. Generally explanations of domain should be limited to

providing contextually necessary information, and tutorials that are heavily domain

specific may be more appropriate for the Scientific Python

`blog<https://blog.scientific-python.org/>`_.

.. _content-examples:

Examples gallery

The gallery of examples contains visual demonstrations of Matplotlib features. Gallery

examples exist so that users can scan through visual examples. Unlike tutorials or user

guides, gallery examples teach by demonstration, rather than by instruction or

explanation.

Gallery examples should avoid instruction or excessive explanation except for brief

clarifying code comments. Instead, they can tag related concepts and/or link to relevant

tutorials or user guides.

Format

All:ref:`examples-index` should aim to follow the following format:

* Title: 1-6 words, descriptive of content

* Subtitle: 10-50 words, action-oriented description of the example subject

* Image: a clear demonstration of the subject, showing edge cases and different

applications if possible

* Code + Text (optional): code, commented as appropriate + written text to add context

if necessary

Example:

The ``bbox_intersect`` gallery example demonstrates the point of visual examples:

* this example is "messy" in that it's hard to categorize, but the gallery is the right

spot for it because it makes sense to find it by visual search

*:doc:`../gallery/misc/bbox_intersect`

.. _content-api:

API reference

The pages in:file:`doc/api` are purely technical definitions of layout; therefore new

API reference documentation should be added to the module docstring to keep all API

reference documentation about a module together. The API reference documentation

describes the library interfaces, i.e. inputs, outputs, and expected behavior. For

guidance on writing docstrings, see:ref:`writing-docstrings`

..grid-item-card::