Repository navigation
[Doc]: Improvements /sorting content for Quickstart Guide / Matplotlib Application Interfaces #29282
Description
Documentation Link
https://matplotlib.org/devdocs/users/explain/figure/api_interfaces.html
https://matplotlib.org/devdocs/users/explain/quick_start.html
Problem
Follow up with ideas discussed in #29272
Suggested improvement
Motivation:
- Matplotlib interfaces should be reference style documentation
- Quick start should be tutorial style documentation
Topics:
-
From https://matplotlib.org/devdocs/users/explain/quick_start.html#the-explicit-and-the-implicit-interfaces remove
(In addition, there is a third approach, for the case when embedding Matplotlib in a GUI application, which completely drops pyplot, even for figure creation. See the corresponding section in the gallery for more info: Embedding Matplotlib in graphical user interfaces.)
This is an advanced topic and not suited for "Quick Start" -
Instead create a dedicated section in https://matplotlib.org/devdocs/users/explain/figure/api_interfaces.html, also include DOC: Add section on translating between Axes and pyplot interface #29272 (comment)
-
Rethink whether we can make https://matplotlib.org/devdocs/users/explain/quick_start.html#coding-styles more approachable. - Instead of just stating the two styles with (relatively complex) examples, give a brief guidance (Quick start should be tutorial-style not reference-style).
-
Optionally: https://matplotlib.org/devdocs/users/explain/figure/api_interfaces.html#third-party-library-data-object-interfaces could be expanded to explain how pandas plots work, i.e. every plot function creates a new Figure and Axes unless an Axes is passed in. As with
pyplot, this does not require an explicit Axes, but the implicit behavior is different (new Axes vs. reuse current Axes). While strictly not our responsibility, this addition may be helpful.
Activity
story645 commentedon Dec 11, 2024
I was thinking explain style, but structured kinda around visual variables:
I go back and forth on aesthetic first or mark type first, but I think having a consistent ordering/structure would make it a lot easier to build associations between "this artist class (and therefore these plot types) supports these visual stylings/parameters"
timhoffm commentedon Dec 11, 2024
Maybe that's the fundamental question we should clarify first.
I see "Quick start" as the entry point for new users (similar to 10 minutes to pandas). The goal is that users can get productive and do their first plots relatively quickly. Do we agree so far?
Coming from https://docs.divio.com/documentation-system/
IMHO the focus should be on learning. Of course, they have to understand some concepts, but only as far as is needed to get a plot done. From https://docs.divio.com/documentation-system/explanation/:
And that's not the goal of a quick start.
jklymak commentedon Dec 11, 2024
The quick start is definitely a tutorial. However even tutorials need to occasionally have some explanation if it is something that trips up many users at the beginning.
I think what happened here was the initial explanation of the difference between the interfaces was in the Quick Start, and then it got expanded because it was not explained anywhere else. Now that we have a more complete Users Guide, making this section of the Quick Start more concise with links for further explanation deeper into the UG makes good sense.
story645 commentedon Dec 11, 2024
Yes, I agree that quick start should be a broad overview of what folks can do/how to do the basic things.
On breaking down the structure of the Pandas overview, I'm revising my take on it being a tutorial but the thing I think is most important is that it's an end to end overview of the library - it gives very brief and sometimes incomplete code snippets b/c it's more focused on showing what and specific thing is and how to do just the thing.
And the only reason I'm stressing this is that my major issue w/ the current quick start guide is the structure. I think cleaning up the examples should fall out of the restructuring b/c like w/ the interface examples, they mostly grew unwieldy b/c of scope creep.
What I mean is take the pandas structure - it's "make data frame, view data data, subset, compute, merge/group/join/pivot, units, plotting, save out" That's a standard intro work process for a table and like concepts are grouped together.
Ours doesn't have as strong a narrative thread, (like coding style should probably be first if it's the info you need to know to understand why all the code is written the way it is...) and if you don't understand Matplotlib, it's unclear why ticks isn't under labeling data and if you don't know Matplotlib then styling artists doesn't mean anything and if you know a little it's not obvious why colormapping gets it's own thing (and also should be updated w/ the new colormapper).
That's why I'm proposing restructure where either the reader walks the work path one plot type family at a time (mark/artist first) or top level visual variable/styling/labeling where the reader walks the work path and sees an example for each plotting type in a consistent order.
And to be clear, none of this is meant as a critique of the efforts that went into writing it - getting it down in the first place makes it much easier to suggest an improved structure b/c there's something to work w/.