Given that this is clearly a lot of work, what's the motivation for this section/this new set of docs? What problem/questions from folks are you seeing that you're trying to solve here that's not currently being addressed in the gallery?

I'll ping for a review for this. Obviously this can just be considered scaffolding.

I believe I addressed why the gallery is not a replacement for explaining how to make plots in the User Guide in the PR description. The gallery will never be a cohesive introductory guide, and I think that is fine. The approach here is to provide a basic start with links to more examples in the appropriate section of the gallery, or elsewhere in the User Guide.

I'm slightly annoyed by the structural duplication of this page and "Plot types".

This was deliberately done so that they would present material in the same order but with more depth than in the quick visual index of "Plot Types". I'm not sure I understand the annoyance - particularly given that I made the Plot Types PR.

MHO this would work better if

you first create an issue describing the topic, and the idea for the stuctural solution (optionally/alternatively make a proof-> of-concept PR for the structure). We could then agree on a the structure first.
then make a PR that puts the desired structure in place
after that, add multiple PRs for the individual sections.
This would keep the PRs smaller and more focused and significantly ease reviewing.

I'd consider this the proof of concept PR. If you have serious objections to the structure, folks could propose alternates. If not, I'd suggest this PR is better than nothing, which is what we currently have. If folks disagree and feel it is worse than nothing, then we should close the PR and continue to have a large gap in the docs.

If folks disagree and feel it is worse than nothing, then we should close the PR and continue to have a large gap in the docs.

I'm not sure what gap it is you're trying to fill with these docs. The plot type gallery is already heavily curated, so I don't think that the narrative is adding much here.

Some of the examples feel so bogged down with extras that I'm not sure that readers will pick up the pattern that I think is what you're trying to convey, and information on how to use each specific function.

I think if there's a gap here, it's in understanding the artists that back the plots and I'd orient the user guide plotting section around those underlying artists.

The User guide has how to make a figure, how to make an axes, ...., a bunch of complicated stuff. I don't think "go look at the plot types gallery" is a good substitute for that middle ground, and I don't think the plot types gallery ties visualizations together in a hierarchy other than their ordering. Which is great - I look at the plot type gallery as a quick overview of what the library can do that a user can quickly scan to see if their chosen visualization is there, and see what we call it.

This new section of the User Guide should get into more details and connect the visualizations which is what I tried to start here. For sure, adding more detail about the underlying artists could be helpful, though I'd perhaps not ruin the flow so much as show a few examples of using the artists, and link out to the API docs or explanation elsewhere in the the Guide.

Some of the examples feel so bogged down with extras

I'm not sure what you are referring to here, but the examples are meant to be semi complete visualizations in most cases. If folks feel something got too far into the weeds, they are welcome to propose scaling a section back or breaking it into components.

I do somewhat feel you are expressing two contradictory ideas of what this section is meant for; "more details about underlying artists" and "fewer extras" are pulling in opposite directions. Obviously writing examples is a balancing act, and folks should feel free to edit this first pass all they want.

The User guide has how to make a figure, how to make an axes, ...., a bunch of complicated stuff.

That's because the user guide introduces the concept of a figure, axes, colormap, etc, all of which are backed by objects. There's not a concept of a plot in the same manner, the closest being the artists that underlie the plot. And it covers the basics of how to make a plot in getting started and in the discussions of the library components relevant for that plot.

I'm not sure what you are referring to here, but the examples are meant to be semi complete visualizations in most cases.

For example, this gets so bogged down in the user warning (which is better explained in the API docs) that it loses focus on how to use the function (if that's the goal)
https://github.com/matplotlib/matplotlib/blob/2a0455e40a990bec76f671ef2d9be0cf7f6ea4af/galleries/users_explain/plotting/gridded.py#L95C5-L118

For example, the focus here is on setting up the data, the actual usage of the function not changing from the usage above:

For example, the goal of this example is presumably to contrast the two, which a reader can pick up from the gallery thumbnails:

https://github.com/matplotlib/matplotlib/blob/2a0455e40a990bec76f671ef2d9be0cf7f6ea4af/galleries/users_explain/plotting/gridded.py#L150C5-L173

I do somewhat feel you are expressing two contradictory ideas of what this section is meant for; "more details about underlying artists" and "fewer extras" are pulling in opposite directions.

What I mean by focusing on the artist is more documents in the style of https://matplotlib.org/devdocs/users/explain/artists/imshow_extent.html. It unpacks a characteristic of ImageBase objects that once the reader understands it, they can then apply that understanding to every plotting method that takes an extent keyword.

That's because the user guide introduces the concept of a figure, axes, colormap, etc, all of which are backed by objects. There's not a concept of a plot in the same manner, the closest being the artists that underlie the plot. And it covers the basics of how to make a plot in getting started and in the discussions of the library components relevant for that plot.

From my point of view people need to be able to make a figure, make and axes, and then make visualizations in those figures and axes. The User Guide as it stands does not have that last step. They are all underscored by objects, so I'm not following what that has to do with explaining how to use the library.

For example, this gets so bogged down in the user warning (which is better explained in the API docs) that it loses focus on how to use the function (if that's the goal)

What I mean by focusing on the artist is more documents in the style of https://matplotlib.org/devdocs/users/explain/artists/imshow_extent.html.

I'd say both of these are somewhat asides that help the user better use the library. You could easily argue that the asides should be in a separate page or put in-line. But I don't think a deep-dive on every artist type and its quirks is the right level for the top-section of the user guide. From my point of view, if it can be explained quickly, inline is OK, if not then it should be linked out to a dedicated subpage.

I give one high-level comment, other than that I'm out of the details here, because the PR gives me a mental overload:

I definitively see a place for a more detailed usage description of (some) plotting functions.
Examples:

• plot() needs explanition at least on (i) plotting lines and/or markers, (ii) the use of the shorthand fmt string plot(x, y, 'r-') vs. keyword arguments; (iii) an explantion that and why the result is a list of Line2D and not a single Line2D plus the tuple-unpacking trick to put it into a single variable.
• imshow() should have a basic explanation how to use color limits and colormaps for simple cases (not going deep dive into the data->color pipeline).

The user guide is certianly the right place for this. (How to plot with lines / markers / images). I'm not clear though on the framing / perspective. I'm feeling that the focus on "plotting methods" (Document: Using matplotlib > Plotting methods, and using method names as the sections) is wrong for a user guide. I think it should instead be something like "Using matplotlib > Visualizing different kinds of data". Then the subsections "pairwise data", "statistical plots", ... in here are ok. But within these sections again, it should not be methods but "drawing lines, markers, bars, ..." etc.

From my point of view people need to be able to make a figure, make and axes, and then make visualizations in those figures and axes. The User Guide as it stands does not have that last step. They are all underscored by objects, so I'm not following what that has to do with explaining how to use the library.

Because those sections are focused on explaining what a figure (object) is and how to create it, what an axes (object) is and how to create it, etc.

@timhoffm is also suggesting by artist here, just implicitly:

But within these sections again, it should not be methods but "drawing lines, markers, bars, ..." etc.

Because each of those visual elements is backed by a different artist.

@timhoffm is also suggesting by artist here, just implicitly:

But within these sections again, it should not be methods but "drawing lines, markers, bars, ..." etc.
Because each of those visual elements is backed by a different artist.

To be precise, I'm suggesting by kind of visualization. There's a strong parallel between "kind of visualization" and Artists, but it's not exactly 1:1 (lines = Line2D, markers = Line2D). And my point is that the user guide should be written from the perspective what the user wants (e.g. a color-coded visualization of 2D data) not what we provide (a method imshow() or an AxesImage). We should structure by the former and explain how to realize it using the latter.

And my point is that the user guide should be written from the perspective what the user wants

Sure agreed. That is basically what the current version does. It explains the type of data to be visualized and then explains the different methods to accomplish that. We don't want these to be completely abstract. Users should learn out names for things. And they should also learn the differences between the methods.

Because those sections are focused on explaining what a figure (object) is and how to create it, what an axes (object) is and how to create it, etc.

I think you are making a distinction here that the original author of those sections didn't intend.

However, the practical difference between an Axes object and a Line2d object is that you need to call many methods on the Axes object to use the library at all (or use pyplot). On the other hand, you could make hundreds of complicated visualizations using Line2d artists and not know any of the methods on that artist, or that the artist object even exists.

Not at all to argue that these sections should avoid mentioning or using artists, just that I don't think that should be a focus at the top level.

That is basically what the current version does. It explains the type of data to be visualized and then explains the different methods to accomplish that.

But what @timhoffm (and I agree) is saying is it should be grouped by visualization task. I think some of this is fixable with subheadings saying things like "Plotting lines", etc...

I think what's getting jumbled up here is that method and task aren't a 1:1 either. Like scatter plots can be made using .plot or .scatter, line plots can be made using .plot, and for special types of lines .vlines, .hlines, .axline, .event and
.stem, .stair and .step (all of which I think can be accomplished with .plot)

But what @timhoffm (and I agree) is saying is it should be grouped by visualization task. I think some of this is fixable with subheadings saying things like "Plotting lines", etc...

The current headings are:

• Plotting Methods
  • Pairwise data
  • Statistical plots
  • Gridden plots
  • Unstructured data
  • 3d and volumetric data

The sections start with a short intro about the type of data to be visualized, and then are indeed subsectioned by method type. So taking "Pairwise data" , it has

• plot
• fill_between, fill_betweenx, and stackplot
• errorbar
• scatter
• bar and stem
• step and stairs

we could maybe expand the description of things you do with pairwise data a bit at the beginning, but this is pretty obvious thing to do with your data. We could also change the headings, but to what without being too verbose? "plot" -> "plotting lines and markers, one color and marker at a time" "fill_between"-> "indicating regions around a line"?

The first sentence of each of these sections basically says what the primary goal of the method is, so in my opinion it's clearest just to use the method name. New users may not know our names for things, but the hope is they can realize they want to plot pairwise data, and then skim the plots for the method most suited to their visualization and then read more.

My only request would be that you add a documentation section next to https://matplotlib.org/devdocs/devel/document.html#examples-guidelines and https://matplotlib.org/devdocs/devel/document.html#plot-types-guidelines that describes intent and recommendations of this new part of the docs.

Sure, done. I added a section on tutorials as well since that was missing, and updated the table to have a bit of info about the goal of each section of the galleries, made that a subsection, and added a link near the table to the subsection.

Note this is a separate commit: 2bb91bb

Edit: see https://output.circle-artifacts.com/output/job/f5d8cef0-00ee-4839-9149-67e13aa61731/artifacts/0/doc/build/html/devel/document.html#create-examples-and-tutorials

On a side note, I believe our "User Guide" is both "Explanation" (e.g. Introduction to Artists) and "How-to" (e.g. Faster Rendering Using Blitting). That may or may not be good, but is out of scope for this PR.

The important part is that we agree on which category "Plotting data" is. I agree with @jklymak (#29124 (comment)) that "Plotting data" is a "How-to". Essentially,

1. How do I plot [data type]"? - Decide on the kind of visualization you want and follow up with the respective plotting function in 2.
2. How do I use [plotting function]? - Learn how to pass your data into the function and some relevant customizations (mostly kwargs).

I like the tutorials section. 👍

I'm unclear on the user guide section, which also stems from the fact that the user guide is currently "How-to" and "Explanation". I would not bother on trying to define this now and here. Just the "plotting data" section should be enough.

I'm unclear on the user guide section, which also stems from the fact that the user guide is currently "How-to" and "Explanation". I would not bother on trying to define this now and here. Just the "plotting data" section should be enough.

Sorry to cross talk in #31496...

As I state there, I think it's awkward to discuss a subsection of the User Guide like it is standalone. The point of this PR is that it is a gap in the current User Guide.

The important part is that we agree on which category "Plotting data" is. I agree with @jklymak (#29124 (comment)) that "Plotting data" is a "How-to". Essentially,

How do I plot [data type]"? - Decide on the kind of visualization you want and follow up with the respective plotting function in 2.
How do I use [plotting function]? - Learn how to pass your data into the function and some relevant customizations (mostly kwargs).

The plot type gallery solves one, the links out into the API docs which point to the minigallery that goes to the examples solves two. So what's the value add here? ETA2; What I mean is, what makes this different enough from the minigallery->examples pathway that it's worth maintaining a whole set of docs rather than signposting that pathway better? (We can always add a "what's next? learn to plot through the example gallery" card)

ETA: in particular I'm thinking of examples like pie.

So what's the value add here? ETA2; What I mean is, what makes this different enough from the minigallery->examples pathway that it's worth maintaining a whole set of docs rather than signposting that pathway better? (We can always add a "what's next? learn to plot through the example gallery" card)

ETA: in particular I'm thinking of examples like pie.

Examples are rather anecdotal. They teach by demonstration, rather than by explanation or instruction. Because the visualization and preview image have a strong weight, I'd consider it rather an anti-pattern for examples to have many plots.

In that sense, some of the examples, including pie are actually very much the type of content, I'd like to see under "Plotting data" and should be moved there. (they are currently in the examples category because we don't have a dedicated place for them).

Another example of "Plotting data" content: plot() should roughly describe accepted data (plot(y), plot(x, y), plot(x, Y)), styling using kwargs, styling shortcuts using fmt. That's not something we can reasonably put into an example.

some of the examples, including pie are actually very much the type of content, I'd like to see under "Plotting data" and should be moved there

Agree, argued something similar in #27459 or the discussions around it, (which honestly my motivation there is the same as one of my concerns here - focus is too much on what's being plotted, not enough on how to plot it) and discussions around it. But that's also a very different approach from the one taken in this PR. I'm also deeply skeptical of the "well then rework on next PR to that style" b/c it will run headlong into the same issues as #27459

some of the examples, including pie are actually very much the type of content, I'd like to see under "Plotting data" and should be moved there.

Yes, that'd be great - not including pie is an oversight, not a deliberate omission. There are likely others.

I'd indeed go through the Examples and do some pruning - some of the material is already cribbed from examples, and probably more could be done.

As a side note/feedback: I wasn't able to easily see whether #29124 (comment) and the subsequent force-push did change pie or whether that was just a communication of intent. This unerpins my point that the PR is too large in scope and content to be reviewable. While I rejoined the conceptual high-level discussion, I still won't systematically look at the actual content of the PR.

No pie is not included. As I'm sure many other things are not either.

A bit of backstory.

The documentation has had some long-recognized structural challenges:

• The galleries were extensive, but not always easy to navigate consistently.
• The Tutorials included strong content, but the Beginner/Intermediate/Advanced split was not always the most effective way to support topic-focused learning.
• Tutorial pages also served different purposes: some were walkthroughs, while others were closer to reference material.
• The User Guide contained important material, but over time it also became a home for a wide range of topics that did not clearly fit elsewhere.

Addressing this required clearing a few technical hurdles:

• Moving content without breaking links was difficult. We improved this by adding a redirect system (Doc implement reredirects #19456). Cloudflare-based redirects may reduce some of this burden, though they still require maintainer setup.
• It was not possible to mix rst and py-style documentation in the way we needed. That was addressed in sphinx-gallery (ENH: allow rst files to pass through sphinx-gallery/sphinx-gallery#1071). Other approaches might also work, but this gave us useful flexibility.

With those pieces in place, we could restructure the User Guide as a sphinx-gallery and move substantial tutorial material into it (#25395), while also adding new content to fill gaps.

Alongside technical constraints, there was also a process challenge: many good ideas were discussed over time (summits, surveys, working groups, sprints, outside expertise), but progress remained slow. Those approaches can still be valuable, but for this specific problem it also seemed important to make practical, iterative improvements in parallel.

My view is that this work was less about finding a perfect information architecture up front and more about putting a clear starting structure in place, then improving it through feedback. Once that structure exists, feedback tends to become more specific and actionable.

From that perspective, I believe #29124 is a constructive step forward, even if it is not final. If the project prefers a different direction, it can choose that. Either way, I hope this helps move the docs discussion from general complaints to concrete improvements.

but over time it also became a home for a wide range of topics that did not clearly fit elsewhere
Once that structure exists, feedback tends to become more specific and actionable.

Most of the discussion here and in #31496 is about getting consensus on structure and content guidelines, so I don't think anyone disagrees on the problems.

The reason for the discussion is I think:

• agreement on what scope to try and avoid scope creep
• agreement on structure b/c structure is really difficult to change, especially b/c everything will need redirects
• enough agreement on scope/structure/mode that folks understand what a new addition to this section should look like.

A major reason the user guide doesn't get touched is it feels like there really isn't space to make new changes - nobody knows what "improving" looks like. Which that's an underlying goal here, to get some clear consensus on what "improving" means b/c we can translate that into guidance and actionable tasks.

ETA: otherwise I think we're mostly just kicking this discussion down the road 'til the next time someone who feels empowered to make these changes makes them, and our goal should be to empower any contributor to make them.

No pie is not included. As I'm sure many other things are not either.

So let me be a bit more concrete here on one of the main things I (and I think @timhoffm) am looking for: how does pie get added?

Can't wholesale move pie features b/c the current structure puts all plots for each data type on one page. Can't c&p the contents into the current doc b/c that'd take up the whole page & the structure doesn't meld w/ what's there. Removing the structure kills what makes the example useful - easy to see what each unique parameter does.

Do folks do something else? What? Which parts of pie get highlighted? Or do follow ups restructure to each plot getting its own page? Under broader data type sections? W/ consistent structure/format to follow?

ETA: and just to be explicit/clear, I absolutely do not want you to just add pie to this PR. What I wanna know is what's the path forward for anybody else who'd like to build on this PR.

how does pie get added?

I'd put in statistical plots. I'd have a short explanation of the type of data that gets input, and an example of basic use, followed by a couple of examples of important styling or common advanced use (in this case perhaps colouring the slices, and probably labelling them), and then list and reference the API page and some of the more advanced features in the examples (hatching, exploding, etc).

The goal is that people have a basic idea of what pie is, and what its flexibility is, and then they can drill down. "A couple of examples" would be a judgement call, as would putting it in "statistical plot", as would the level of explanation or how it is explained.

I think this is largely covered by

The material should stay relatively balanced and move between basic and more
advanced concepts in as natural a manner as possible. The goal is for a user to
read the material without having to spend too much effort trying to understand
the examples. Deep dives into one feature set should usually live elsewhere and
be linked as further reading when appropriate.

some of the more advanced features in the examples (hatching, exploding, etc).

hatching is basic accessibility, which is not me trying to be annoying so much as trying to flag that "basic" and "advanced" are subjective criteria, usually determined by the conventions of a specific field. Which is how doc prs get derailed on "does this belong?".

That's a big reason why I think "comprehensive" (like pie features) makes more sense for a guide - it's basically a checklist of "is using this parameter explained with an example?"

ETA2: Which this isn't even a request for you to make these changes here, just the direction I think changes should move to improve upon what's here.

ETA: A big goal being that we can then refine the example gallery to be much more focused on fully exploring parameter space. So user guide shows how to use a colormap, example gallery shows all the common and weird ways colormaps can be used.

ETA3: Annotation Guide functionally is this - the basic section and first half of advanced section is basically a comprehensive guide to the annotate method. Also subplot mosaic for the subplot_mosaic method.

hatching is basic accessibility, which is not me trying to be annoying so much as trying to flag that "basic" and "advanced" are subjective criteria, usually determined by the conventions of a specific field. Which is how doc prs get derailed on "does this belong?".

Yes, and that is absolutely why I'm not breaking this PR into 20 or 30 separate PRs, because I have zero interest in having all those debates that end up 10 times longer than the PR.

because I have zero interest in having all those debates that end up 10 times longer than the PR.

That's also why this PR isn't moving forward - b/c I don't want us stuck in a situation where every single follow up to this PR ends up in those debates such that nobody makes follow ups.

ETA: And why I think the criteria should be the more objective "comprehensive" rather than the subjective "basic"

Also, gonna be super frank here @jklymak. This PR is too big for most folks to sensibly review (1) and you've said you don't have the time (and indicated the inclination) to make significant changes (2). Were this PR authored by almost anybody else, it would at best have been met with a "thanks, we're gonna put this in draft until you have time to really engage with the feedback" if not tagged w/ an autoclose label. It's basically only out of respect for your work and for Tom thinking this PR is a good idea that I (and maybe Tim's motivation is similar) am trying to figure out a consensus for the next steps that will definitely need to happen on account of 1 & 2.

And no "merge despite all my misgivings such that Jody is the only person who can maintain this" is not a path forward.

So to be concrete, what I see as maintenance issues here is roughly the same as why it's difficult to review. There's too much content crammed together w/ unclear criteria for inclusion of examples. I'm proposing one plot type per page b/c that keeps each page smallish and well scoped (and therefore easier to review and update) and comprehensive as the inclusion criteria b/c it's fairly objective. You're welcome to disagree, but just either explain why your current PR is more maintainable than my proposal or propose a scheme you think is more maintainable. (Edit, which really, I'd break this PR into 6 - one per plot type section + one for guidelines - not 20 or 30).

I am not sure what you mean by "plot type". I've not seen where you are "proposing one plot type per page" in any detail for me to compare against.

Guessing: If you mean one plot method per page (eg plot, scatter etc), that would be unreadable as a table of contents, even if you ordered them somehow, which I hope is not what you are talking about.

Barring that, organizing the individual methods is basically what this PR does, but instead of one page per method, it has one page per visualization type, and the individual methods are subsection. I would argue that isn't "cramming" anything, or any more difficult to maintain than breaking up into individual files. It also has the benefit of having an introduction explaining the grouping. If you want the listing of all the individual plotting methods, just increase the index depth.

With regards to comprehensiveness, that would basically mean taking 95% of the example material and moving it into the User Guide. That maybe is something that could be considered, but I think "get a good idea and link out" is easier on the reader and a good start.

Guessing: If you mean one plot method per page (eg plot, scatter etc), that would be unreadable as a table of contents, even if you ordered them somehow, which I hope is not what you are talking about.

This is the proposal from #31496 (comment) of repurposing the plot gallery content pages as plot method guides. So essentially the plot type gallery becomes the TOC and on the user guide we can just have the first level plot type that you have here.

ETA: Which, it's quite likely our users would just jump to the plotting guide and then go back to the other sections of the user guide as needed b/c plotting is the priority.

It also has the benefit of having an introduction explaining the grouping.

This would move to an index page for each of the folders that already exist in plot_types, similar to what we already do for text and colors

I would argue that isn't "cramming" anything, or any more difficult to maintain than breaking up into individual files.

It's a lot harder to find/keep place in the doc b/c it has so much going on. That's what's making it so hard to review. And to see if/what is missing. Narrowing to one method per page makes it easier to (relatively quickly) get a per method overview w/o having to think about the other things on that page.

that would basically mean taking 95% of the example material and moving it into the User Guide.

This is why I'm so adamant on one example per kwarg visual overview of API (what the parameter does vs all the ways to use the parameter). For pie it would be pie features, not everything in pie and polar examples. For histogram it would mostly just be histogram bins, density, and weight - whatever my objections to how it's structured/where it's focused, it's an overview of the parameters/using the function. Which right, this belongs in user guide but would absolutely swamp the stats section.

I think your proposal, as described here, would be useful reference material, but would be a level below (or adjacent) to a User Guide.

Narrowing to one method per page makes it easier to (relatively quickly) get a per method overview w/o having to think about the other things on that page.

Separate pages are hard to read together. You need to read your section, go back, and then click the next subject. That is fine for reference material - it breaks up a narrative.

This is why I'm so adamant on one example per kwarg

For most methods this would be unreasonable level of detail for a beginning User Guide; I'd argue a comprehensive kwarg scan would be better placed in a "Further reading section" and live elsewhere.

Overall, what you are suggesting sounds like reference material to me, not a Users Guide. I don't object to that at all, but it is orthogonal to the proposal here.

(BTW I did not see that scoped out in the comment you linked, which is by @timhoffm #31496 (comment) and definitely does not say that there should either be a single page per method nor that there should be a kwarg scan on each page, so perhaps you linked the wrong comment?)

Hm, I may slowly better understand the different motives here. @jklymak I now wrote a documentation section, which I requested for this PR here to the scope I now believe you are trying to deliver. Is this correct?

Plotting data

The section Plotting data of the Users guide showcases plot types as a guided walk-through. The user should learn what is available (e.g. pairwise data can be visualized as lines and/or markers) and how to achieve this (e.g. using plot()). Focus is primarily on the visual outcome. We explain plotting functions and relevant parameters only to the level necessary to generate that outcome (e.g. do not discuss all call signatures for the data values of plot(); do mention the marker parameter, but do not extensively discuss styling like color or linewidth).

Show by visual example. The user should have a basic first idea by only looking the plots. Each visualization should be introduced by a brief explanation to set the stage. Cross-link related documentation; primarily the API documentation, but also tutorials and examples if appropriate.

That at least would make sense to me, and in this context, putting multiple functions on one page is fine. There are some places the PR deviates a bit from the scope and could be more concise, but overall this is a direction we can go.

IMHO @story645 and me are hitting another scope. @story645 please correct if I'm wrong.

Plotting functions

The section Plotting functions of the Users guide explains common usage patterns and parameters of common plotting functions. The user should learn how the respective function is typically used. Explain typical call signatures (e.g. for plot(): x, y, y, x, Y, but not x, y, x2, y2) and parameters (e.g. for plot()` the fmt parameter, common styling). Each mentioned aspect should be illustrated in a plot. Use separate plots or aggregate multiple aspects (e.g. common styling parameters) into one plot as appropriate.

The section should contain one page per function. Link that page from Plot types and from the function's API. Cross-link related documentation; primarily the API documentation, but also tutorials and examples if appropriate.

I think we can do both and with good scoping we reduce the risk of creating a mess. Feel free to comment on the overall idea of this scope distinction and/or specific definitions I wrote in these doc proposals (preferably first general idea, and later bikeshedding specifics).