I was told to discuss docs here. I can't parse most of what is being said above, however at #28708 it was stated more succinctly that

I think adding one more section to that document so it's an even larger collection of related but disjoint topics would make that page even harder to maintain and the documentation even more undiscoverable

which I largely don't agree with - the page, https://matplotlib.org/stable/users/explain/figure/interactive.html, is the top hit for a google search on "Matplotlib interactivity" so it is very discoverable. In the table of contents it is under "User Guide->Figures->Interacting with Figures" which seems as reasonable a place as any.

"related but disjoint" is an oxymoron; I would write that page a bit differently, and I think it could be modernized, but it seems to flow pretty naturally - this is how you get a GUI, here is how you can interact with it.

"harder to maintain" - sections and subsections in a document don't strike me as hard to maintain.

Conversely

The reason for "everything gets its own page" is b/c I think tighter scoping

every paragraph or subsection getting its own page will be very hard to maintain; if I need to add a topic or modify a topic I need to first figure out if a page exists, read the possible relevant ones, and then either add a page or modify one or more of the existing ones. A single page with good subsections is a quick search/skim of the headings. I feel pretty strongly that the scope of the existing page is fine, and the number of topics in it is appropriate and both "discoverable" and "maintainable". People learn much better from books than flashcards.

I'm 👍 for improving https://matplotlib.org/stable/users/explain/figure/interactive.html maybe with some mild reorganization, and some salient additions would be great. But I think tearing it apart and starting from scratch is not a good plan.

"related but disjoint" is an oxymoron; I would write that page a bit differently, and I think it could be modernized, but it seems to flow pretty naturally - this is how you get a GUI, here is how you can interact with it.

Related but disjoint is also how I'd describe the relationship between norms and colormapping -> the norms are used in colormapping, but they're also a standalone topic.

The page structure you propose isn't the current structure. The current structure is:

• here's how to interact w/ a figure in a REPL
  • here's some IPYTHON specific stuff
• here's a breakdown of the GUI navigation we offer
• here's how to load backends

But I think tearing it apart and starting from scratch is not a good plan.
People learn much better from books than flashcards.

Why do you say that breaking concepts up into their own page w/ distinct purpose is making flashcards and not chapters in a book?

Again, my proposal was break things up in the following way:

• new page: overview of out of the box interactions
• move existing content to new page: how do I interact with a live figure in a repl
• move existing content to new page: GUI navigation/toolbar - overview, features, keybindings,
  • which now is a good launch point for introducing documenting/widgets
• move existing content to different existing page: loading interactive GUIs
• repurpose existing page/url-> interactive.html as intro to how mpl enables building interactive viz

In the table of contents it is under "User Guide->Figures->Interacting with Figures" which seems as reasonable a place as any.

"interacting with figures" is very broad and half that section is about backends. Which yes architecturally is deeply linked with interactivity, but generally from a "making visualizations" point of view interactivity is a distinct topic that focuses on the interactions:

• is a separate chapter in visualization textbooks like Visualization Analysis and Design
• is a separate section of docs even in libraries that specialize in interaction like bokeh, d3, and altair
• is it's own subfield in the viz literature

ETA: I think that the current structure blends the what: interactivity with the how: backends/guis in a way that I think ends up making the what hard to find for folks who don't already know what the how is trying to achieve.

he page, https://matplotlib.org/stable/users/explain/figure/interactive.html, is the top hit for a google search on "Matplotlib interactivity" so it is very discoverable.

I'd probably repurpose that url as the landing page/overview of the whole interactivity section so wouldn't lose that. What I mean though is that page doesn't lead you to discover the 'out of the box" techniques or #19037 or widgets or many of the other nice things MPL offers for you to build your own interactive viz. Which is why I'd want to repurpose that page into an overview of what we offer for folks to build out viz.