can these be one column/ two lines?

I didn't take this suggestion..

It just takes up a lot of white space/is particularly bad on mobile:

I think that's the sticking point - the difference between user guide and example shouldn't just be that user guide is longer.

"...just be that the user guide is longer" is not what these sentences are meant to convey.

That's what "more than" conveys.

Again, I think the full three paragraphs conveys a lot more than that. If that is all you got out of it, edit suggestions, or comments about what you didn't understand are welcome to make the point clearer.

What I'm not understanding is if structurally/modally there's supposed to be anything different about a user guide page vs. a tutorial or user guide page vs. an example.

Like "Customizing Plots" could be a tutorial or a user guide entry or a gallery example. We have it in all three flavors - current rc guide, lifestyle of a plot has a lot of styling guidance, examples w/ a styling:type tag. So what distinguishes it as a user guide entry if it's not just "more explanation"? minimal/focused code is the same guidance as for examples.

• The User Guide should be intentionally organized and largely readable in sequence, at least within each section and ideally across the full guide.
• Tutorials should teach end-to-end visualization workflows, not isolated feature explainers, and should stand alone for readers who have completed the User Guide.
• Examples should be quick visual references: easy to scan, easy to copy, and easy to adapt.

Overlap is expected. But instead of asking “Where does page X belong?”, we should ask, “What does the User Guide need in order to be reasonably comprehensive?”

Honestly, to me some of the examples in this PR don't follow these guidelines. Which I agree w/ in theory, which makes me wonder if we have different definitions of "concept being explained" and "extraneous".

What I'm thinking of in particular is what I see in the comments as digressions on implementation details (aspect, aliasing, color cycles). And also (as I think Tim also mentioned) most of the focus in the preamble of these functions is on the data - I'm feeling like the plotting concept is getting completely lost here.

Matplotlib is a scientific data visualization tool. Usually scientists have data they want to plot, so I think discussing the data types (pairwise, gridded, etc) and various way to represent that data is a relatively useful way to contextualize. It is also exactly how Plot Types is organized. I'm not sure what "plotting concept(s)" are bing lost.

As for digressions, there may indeed be some. It will be a question whether we should add more, or reduce them, but I expect the former. The ones included were ones I felt were important.

The ones included were ones I felt were important.

I think if they're important enough to be mentioned, then they should get a proper subsection/paragraph heading w/ explaination on why you're telling them this. Otherwise it feels like a distraction from whatever they're supposed to be learning in the specific example. Mostly cause someone reading the plotting section of the user guide is likely missing all the context for why this is important to know.

It is also exactly how Plot Types is organized.

B/c plot types is answering the "what chart types can I choose from?" question, while I think user guide is supposed to answer "what can I do w/ the chart type I chose?

I'm not sure what "plotting concept(s)" are bing lost.

For example, the start of the gridded data section is a paragraph and a half on gridded data. There isn't even a brief introduction to the plotting methods, something like "the regular gridded data plotting methods all plot variants of a heatmap, which is a visualization where the data values $Z_{i, j}$ are encoded as colors. Matplotlib does this encoding by mapping the data to color look up values using normalization and then using the normalized values to look up values in the colormap".

Some of this is addressed on the specific methods, but like we both know that it's the $norm \circ cmap$ pipeline that messes up newbies to mpl and that's the core of the heatmap/imshow visualizations,
so that should be top level. Especially since it applies to all the gridded methods. It's definitely not less important than aspect, which somehow gets more emphasis - which also you introduce vmin/vmax before norm but vmin/vmax is just implicit norm.
And the reason for telling users what a heatmap is even though we expect they know is to ensure we're using the same terms.

Sure, first sentence fixed, but note this section is not just about colormapping as contours need not be colored.

As for mapping using norms, a full explanation is linked, and maybe more could be explained here. However, I consider that somewhat intermediate, and I bet 95% of our users never create a norm directly.

but note this section is not just about colormapping as contours need not be colored

That's why I (and I think Tim) were pushing for some/sub organization under viz type. Group heatmap like functions together so all the shared concepts (colormaps, norms) can be discussed under that header and then the function how tos can be streamlined to the function specific differences. Main reason plot types gallery doesn't have that sub organization is b/c we don't go into that level of detail there. Bonus is easier to edit when we add explainations about colorizer later.

However, I consider that somewhat intermediate, and I bet 95% of our users never create a norm directly.

I've probably been using Matplotlib almost 20 years and I don't think I've ever really cared about the aspect but you think it's very important for understanding how to use imshow. Which fine, I think norm is one of those things that's really important to understand even if you don't make one directly b/c it underpins all the colormapping (at least currently).

where? example gallery?

can you define broader workflows b/c I'm struggling w/ how artist tutorial is a broader workflow. Granted, I also think it should be folded into the user guide entry on artists.

These are general guidelines, not meant to cover everything that already exists or be overly binding.

what's the criteria for more cross-cutting and more in depth?

suggestion but the thumbnail?header image should usually be the finished product as that'll give folks the "why do I want to read this?"

The purpose here is not to tell people how to write these. Thumbnails are covered above.

The rest of this paragraph is content suggestions: sections/headings/toc. This is just another content suggestion.