Repository navigation
[Doc]: Add visual key to user guide #26205
Description
Documentation Link
Problem
It's hard to navigate the user guide if you don't know what we call things. Folks should start on the quick start so that they will learn what it's called, but a) we don't indicate that quickstart teaches that indormation, b) a lot of folks don't and we should account for that. attn: @melissawm and @esibinga
Suggested improvement
I was thinking like pull out and streamline the parts of figure part of the quickstart guide and make it a big card. Something like:
Screenshot: Sample layout
If folks like this direction, it can definitely be cleaned up to something pretty and probably slim down the anatomy figure to just the basics. Maybe take the longer descriptions from anatomy and work them into their corresponding intros.
And probably streamlined to just the contents of the userguide index if #26156 gets resolved.
Activity
akshayamadhuri commentedon Jun 29, 2023
@story645 i would like to work on this
story645 commentedon Jun 29, 2023
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?
jklymak commentedon Jun 29, 2023
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.
story645 commentedon Jun 29, 2023
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.
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.
jklymak commentedon Jun 29, 2023
Sorry, confused Quick Start and Getting Started, but I think you get the idea.
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.
story645 commentedon Jun 29, 2023
We should almost definitely be combining quick start and getting started or clarifying the difference b/c clearly it's a source of confusion.
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:
The two most similar to mpl breadcrumb their guides much better:
jklymak commentedon Jun 29, 2023
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!).
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.
story645 commentedon Jun 29, 2023
They don't have a formal glossery, but I think they're all orienting their audience more than we are?
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.
jklymak commentedon Jun 30, 2023
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.
story645 commentedon Jun 30, 2023
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.
jklymak commentedon Jun 30, 2023
It is absolutely our table of contents. Read conf.py. There is discussion of reorganizing where the TOC is in another issue.
jklymak commentedon Jun 30, 2023
story645 commentedon Jun 30, 2023
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
jklymak commentedon Jun 30, 2023
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.
story645 commentedon Jun 30, 2023
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
.
github-actions commentedon Oct 5, 2026
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!
story645 commentedon Oct 5, 2026
I still think this or something like to would be a good idea for orienting readers on the user guide page (which is no longer a a site TOC) but also this is part of a larger discussion on the user guide and therefore not an issue I recommend for new contributors.