@story645 i would like to work on this

Hi @akshayamadhuri thanks for your enthusiasm but I'm really unsure if this would go in any state and I opened this issue more as a place to discuss/sort out if we think it's a good idea. I've coded up the image at https://github.com/story645/matplotlib/blob/parts-of-figure/doc/users/index.rst

ETA: Do you think it's a good idea? Would it make the docs easier for you to follow?

If a new user is confused by what we mean by "figure" or "axes" those are pretty clearly listed in the TOC and explained in the Getting Started. Im not a fan of redefining everything on every page a user may land on as that is distracting to the other 99.99% of people who have already read the Getting Started. If there are issues with the TOC we should address those directly.

Im not a fan of redefining everything on every page a user may land on as that is distracting to the other 99.99% of people who have already read the Getting Started.

It's not in the getting started, only in the quickstart. And my plan would be to remove it from the quickstart and integrate the longer intros into the respective object tutorials. Like you, I'm really not a fan of repeating the same info six times. Also though, the folks who've landed on this page haven't read the quickstart or the getting started yet->that's why they're in this page.

" those are pretty clearly listed in the TOC and explained in the Getting Started.

Yes but if you don't know what they are than you don't know what that means in the TOC -> like you have to know "oh, Axes is the thing I make visuals on, let me look at the Axes" tutorial. Partially it's intended as motivation to read the other things.

Sorry, confused Quick Start and Getting Started, but I think you get the idea.

Yes but if you don't know what they are than you don't know what that means in the TOC -> like you have to know "oh, Axes is the thing I make visuals on, let me look at the Axes" tutorial. Partially it's intended as motivation to read the other things.

If I go to a webpage, and it has a bunch of terminology in the TOC I don't understand, and it has something called "Getting Started" or "Quick Start", then I will read those first. I don't know that I'd expect a glossary in the TOC, and I don't think I'd expect to comprehend every term in the TOC before I read those sections. There is only so much bootstrapping you can do before things become very disorganized.

We should almost definitely be combining quick start and getting started or clarifying the difference b/c clearly it's a source of confusion.

and it has something called "Getting Started" or "Quick Start", then I will read those first.

This idea came up in the GSOD discussion cause all 3 of us felt it'd be useful to have a basic orientation. My use case is that I just want to know what the thing I need to modify is called so I can go to those specific docs -> and honestly like I don't think that's uncommon given how often I've had to link folks to "hey, did you read the getting started" docs? I think there are probably folks who've been using mpl for a while and so don't think of themselves as a get started audience, but don't actually know what we call things -> especially the PyPlot folk.

I guess when I think of "what is the most useful thing for someone reading the docs to know so that they can find what they're looking for" it's what we name things. It's in the docs landing pages for other visualization libraries b/c it's such a common issue:

• https://ggplot2.tidyverse.org/reference/index.html
• https://d3js.org/what-is-d3
• https://vega.github.io/vega/docs/

The two most similar to mpl breadcrumb their guides much better:

• https://plotly.com/python/ <- them it's more really clear names
• https://docs.bokeh.org/en/latest/docs/user_guide.html#userguide

I don't see that any of those have a glossary on the landing page, though I agree that Bokeh has one in their introduction (as do we!).

My use case is that I just want to know what the thing I need to modify is called so I can go to those specific docs -> and honestly like I don't think that's uncommon given how often I've had to link folks to "hey, did you read the getting started" docs?

We all try to jump around in doc pages for things we just want to use, but don't really want to learn. For me it's sphinx, but just because I don't understand many sphinx concepts doesn't mean the sphinx docs are bad.

Anyway, I'm not in favour of duplicating the glossary/Parts of Figure image on the lading page. If you want to move it there, that is less objectionable, but I still think out of place.

They don't have a formal glossery, but I think they're all orienting their audience more than we are?

If you want to move it there, that is less objectionable, but I still think out of place

Yes, the intention is to use the shortened version shown in the screenshot, remove it from quickstart (which possibly merge with getting started), and move the longer descriptions to each of the respective artist intro pages cause there is some good info there.
I also think I'd smooth out by removing the picture in getting started (sorry, I know you just made that).

On a bigger scale, I'd like to push the docs towards a sorta "one source of truth" model as much as possible because yeah duplication makes me twitchy cause it adds a maintenance burden of trying to keep things consistent.

I dont agree that they are orienting their audience more than us. I'd be fine improving Getting Started and Quick Start and maybe merging them. That is where I would expect to see detailed orientation. I would not expect a glossary in the table of contents.

I would not expect a glossary in the table of contents.

Hmm, wondering if this is kinda the heart of the disagreement in that I don't see the user guide landing page as a TOC, I see it as an intro to the user documentation. So I'm thinking of the glossary as breadcrumbs for where they should go next.

It is absolutely our table of contents. Read conf.py. There is discussion of reorganizing where the TOC is in another issue.

It is absolutely our table of contents

I think this is a talking past each other thing - I know that users/index is technically the TOC, but I disagree that that's how that page should function because of where it's positioned in terms of navigation..which is part of the issue in #26156

If you are going to say this page should not be the table of contents then you need to say where the TOC should go, not just add extra info to the existing TOC. In my opinion the proposal here adds to the organization problem rather than helps solve it.

I believe my stance has been consistent. We don't want or need a glossary in the table of contents.

If you are going to say this page should not be the table of contents then you need to say where the TOC should go, not just add extra info to the existing TOC.

I'd just make a proper sitemap page, but if we want something more coherent then the docs landing page as proposed in the issue https://matplotlib.org/devdocs/ is the right page for the docs TOC
.