I think improving the usage guide is a place to start. It has most of your first subsection.

http://matplotlib.org/tutorials/introductory/usage.html#sphx-glr-tutorials-introductory-usage-py

That's indeed a good place, already conating some of my points (though I haven't yet read it completely).

Maybe even more important than changing the contents is making this more accessible. To find it from the main page, I had to

1. http://matplotlib.org/index.html: "To get started, read the User's Guide."
2. http://matplotlib.org/users/index.html: Tutorials -> Introductory
3. http://matplotlib.org/tutorials/index.html#introductory -> Usage Guide

Step 1 is fine, I would never have guessed that I have to follow the links in 2 and 3 to find that information. Maybe part of the problem is the naming. It's more a reference than a tutorial. Also, it's more "Concepts/Structure of matplotlib" than a "User Guide".

Agreed. I think that right now there is no user documentation. The advice I've received is to go ahead and add documentation to the existing structure, which for better or worse is the "tutorials" section, and then a re-organization will happen using that raw material. I think the only caveat there is that tutorials are *.py files, whereas straight *.rst with ..plot:: directives might be a nicer editing format. But its pretty easy to translate the *.py tutorial files to *.rst (because it already happens during the build process). The other issue with tutorials is that they are not in any sensible order, which is another argument for *.rst. Sphinx Gallery arranges them by their length, of all things.

FWIW I believe that although sphinx-gallery is really good for "unstructured" examples where the main focus is sample code and plot, it doesn't work so well for "tutorial/guide" style docs where text is the most important part.
I would support switching these parts of the docs back to plain rst.

wonder how much this ties in w/ MEP #17446

Loosely. #17446 is more specific in that it defines a method how to handle „porperty“ concepts. The docs part of #17446 and this one would live in the same part of the documentation.

Wondering if most of this was addressed in #21641 w/ possibly a follow up issue that basically adds an intro to the transform tutorial to the quick-start guide?

Or are you looking to make a kinda glossary/single source of truth thing - we had one that was removed in #18696 b/c it just listed backends, but a "core concepts in mpl" might not be bad? A different alternative 'cause search is kinda not great is maybe using something like sphinx-tags to catalog some of the related pages?

@story645 Thanks for the ping. I'll check what is available now and reconsider what I want here. Will get back on this later.

This issue has been marked "inactive" because it has been 365 days since the last comment. If this issue is still present in recent Matplotlib releases, or the feature request is still wanted, please leave a comment and this label will be removed. If there are no updates in another 30 days, this issue will be automatically closed, but you are free to re-open or create a new issue if needed. We value issue reports, and this procedure is meant to help us resurface and prioritize issues that have not been addressed yet, not make them disappear. Thanks for your help!

Keeping this open until we can replace with a more actionable roadmap for doing this in docs?