Was trying to pull out just the restructuring from#24493 and every shuffle felt like it wasn't sticking and I think something a couple of us kept coming back to is that the way thenarrative docs are written is conceptually almost indistinguishable from thetutorials.

but I think the more fundamental issue is the awkward match between the rst docs and the tutorials/gallery; much of what is in the tutorials would more logically be called part of a Users Guide.

Originally posted by@jklymak in#24493 (comment)

The tutorials and the narrative docs are both very explanatory and comprehensive, in ways where it's not clear that they're written for different audiences or purposes. I could maybe see the argument that one is written for developers and the other for users, but there's nothing in the UX to sign post that. This leads to confusion about where users should start - guide or tutorial. I also wonder if one of the reasons folks think Matplotlib doesn't provide interactivity is that all the documents explaining how to build interactive visualizations are in the user guide (and it's very unclear why they're there and not in the tutorials.)

Solution

I think an easy solution is to port the8 explanation documents to sphinx-gallery and move them to tutorials. And then possibly change the name of that section to user guides since some of the examples in the gallery border on tutorials anyway...

ETA: just to be clear, this needs a ton of discussion & is very much not ready for a PR.