hannah

I think some of the concern @jklymak is raising is sort of this cycle from diataxes:  which was basically, before I saw it, the motivation for https://github.com/matplotlib/mpl-sphinx-theme/pull/72 So I...

> I'd also prefer we not re-define what should go in each section absent of the substantial work that has already been done. However, I also agree that it is...

> "Users Guide" Narrative explanation for how to use Matplotlib, moving from general intorduction to specific subtopics and explanations, heavily using examples. "Examples" Short self contained documents that have one...

tldr: This is diataxes https://diataxis.fr/map/ > Moving around the map > * learning-oriented phase: We begin by learning, and learning a skill means diving straight in to do it -...

> Repeating my objection: I strongly object to relegating the users guide to simply "learning/explanation" and think it needs to show you how to "push the buttons". It's a matter...

Also that table assumes/can sort current content as written give or take a couple of small reframes/restructures/moves on the scale of the contributing rework. It very much doesn't require major...

> I feel the Getting Started Guide should be considerably shortened, rather than expanded. When originally composed it was the only user guide that the User Guide section had, and...

> Having read it, the reader will come away understanding how to use Matplotlib and have some idea of the concepts that underpin how Matplotlib works. Let me rephrase my...

> explanation of concepts happens along the way by way of comprehensive buttton-pushing examples. Gonna go back to the numpy doc cause I think we have the exact same audience:...

```txt If something is part of a self-contained subject: it would ideally be in the User Guide an accompanying example could also be in the Examples. elif there is no...