Plot types is one of our most visited pages according to the plausible analytics.
https://views.scientific-python.org/matplotlib.org

I'd drop tutorials - it's ill defined and currently mostly folded into user guide . The remaining 5? entries could either be folded into galleries, folded into the relevant user guide section, or we could flesh out tutorials as a proper user guide section down the road.

I don't doubt that Plot Types is heavily visited. I'm just not sure that it needs to be in the top level navigation. Linking from the front page and the top level for sure, just not sure anyone goes two levels deep needs to go back to plot types.

Linking from the front page and the top level for sure, just not sure anyone goes two levels deep needs to go back to plot types.

It's more for the folks who won't go two levels deep. Like it's there so folks who land on our docs can get that overview of what plots they can make because that information is buried in our actual gallery. Which is how it ends up one of our most frequently hit pages.

I really think if we should cut anything it should be tutorials. I don't think there has been a new tutorial in years, and I think it's because it's unclear what this section is for - to users and contributors. We really are down to 4 tutorials, all of which can be nicely integrated into user guide:

• pyplot - this is getting started pyplot version (ETA: also I wonder how many folks are hitting this just b/c they go to tutorial instead of user guide first)
• image - this could either be a long gallery entry or an entry in the plotting section of the user guide
• lifecyle - this overlaps heavily with the current getting started and might work well as a way to structure it
• artist : this should just be consolidated with the artist user guide entry b/c it's more explanatory than the artist user guide entry

Thanks for the links to the plausible. I'd forgotten that was where we moved things...

So for /stable/plot_types/index.html

Entry Page Metrics

I find this a bit confusing, as I'm not sure how folks are getting to this page directly since there are only about 12k searches. I suspect from the brochure site? But regardless, I think this does bear out the idea that most visits are from outside our docs, or the top level?

"Releases" only gets 2.8k visitors, most are direct.

it should be tutorials.

Agreed that tutorials can/should go. It is probably unsatisfying for users to land there. Conversely, ad few more quality tutorials would not be amiss.

BTW I'm not sure what "Direct/None" means on Plausible. It seems possible we are not tracking referrals from the brochure site properly the way we have things set up?

Conversely, ad few more quality tutorials would not be amiss.

Given all the discussions trying to differentiate tutorial from user guide entry and gallery entry, I think it may actually be easier to sort out/define what a tutorial should be if we first drop this section 'cause currently I don't think the pages in it are distinct from user guide entries. Like I mentioned, I think we can start with a small plotting/tutorial section in user guide and if that gets sufficient interest than we can always spin a tutorial top level back out again.

ETA: if there's consensus around melding tutorials into user guide, I can put in the PR to do the consolidation/clean up.

I agree that tutorials in it's current form is not meaningful. I support integrating into user guide.

I think we should also move the icons on the top right to someplace in the footer.

Can we please work to push the docs towards https://diataxis.fr not towards the collapsed state?

Can we please work to push the docs towards https://diataxis.fr/ not towards the collapsed state?

I think a workable way to get to a diataxes like taxonomy would be a bottoms up approach where we start using tags to identify tutorials (in gallery and user guide) and from there use that to build consensus on what the maintainers think a tutorial is.

I think right now removing tutorials is a pragmatic way to have the taxonomy match how our docs are actually structured, because I do not see a stylistic/modal difference between the current 4 "tutorials" and the user guide entries.

ETA: I also strongly think that the docs are already in a blurred state between user guide/tutorial/gallery, and dumping tutorials would at least allow us to have a clearer explanatory/long-form vs. short-form/how to boundary.

I suspect Diataxis is more the structure for "User Guide". The top-level nav is must at least partially work on a higher level.

I suspect Diataxis is more the structure for "User Guide". The top-level nav is must at least partially work on a higher level.

To support this, the contributing guide is a mix of diataxes, where each sub-section roughly fits a modality: #26389 (comment)

I also sorta broke down user guide in #26389 (comment), but also I think that PR got really badly mired in disagreements about learning/teaching styles that influenced how we interpreted the diataxes mappings. I frankly don't see that as resolvable, so I think the pragmatic solution is to accept that the user guide will be written as an explanatory/tutorial mashup and instead we should figure out a consistent subject based modality - like how plot types is now all organized by data continuity.

Where clean divisions fell out of #26389 were the sections that were already tightly scoped: API->reference (which I really should just PR into the docs docs #30085), gallery entries (which is already in doc docs), and plot types (which should also be PR'ed into doc docs #30084).

I also think another possibly more workable (and we may get more contributions) approach to tutorials is to make it it's own repo, like:

• https://github.com/astropy-learn/astropy-tutorials
• https://github.com/numpy/numpy-tutorials

For the main point of this query, it would be useful if someone with access to the Plausible settings were to enable custom events for click tracking: https://plausible.io/docs/custom-event-goals. I don't see any way with Plausible to see what folks are using in the UI elements unless this gets turned on.

I still think that the top level could be:

Guide | Examples | Tutorials | API | Contribute

and I'm 50/50 on "Contribute". "Releases" would be fine on the top level, and "Plot Types" would also be fine on the top level (and "Plot Types" could also be linked at the main gallery)

I would still argue for this, even if we decided to get rid of "Tutorials" all together.

I'm 50/50 on "Contribute"

I see Contribute being top level as a statement of values - this is so important to us we want you to always have access to it. Also we want it to be stupidly easy to find. We switched it to develop for a minute and a half and then pulled it back to contribute b/c the broader term also felt more in line w/ purpose/ethos.

I think there is a case to be made that folks need ready access to Contribute.

Looking as numpy/scipy/pandas, there seems to be a general agreement that the following categories should be in the top level nav (with slight variation in naming):

• User guide
• API reference
• Developer guide
• Release notes

I feel they are all valuable as top-level entires

Other items found in the above docs:

• Installing: I don't think we need this because it's a rare action, and package managers are very standardized nowadays that many people don't need to look up how to install.
• Building from source: This is also rare and can be part either of installing or developer guide
• Getting started: Similar to installing, this is only needed once and access on the entry page should be enough.

I'm fine with not having them in matplotlib

Other items in matplotlib docs:

• Plot types, examples: Showing plots is important for a visualization library. We communicate our features and capabilities through these visuals. They should be easily accessible, which justifies a place in the nav bar.
• Tutorials: Ok to have, but also ok to move into user guide. Somebody who takes the time to go through a tutorial usually can spend the time and effort of one additional navigation level.

Note: I also like the idea of collapsing remaining items into a dropdown if space is rare, as illustrated in pydata/pydata-sphinx-theme#2117 (comment). In our case that would primarily concern Releases and Contributing, which is fine as they may be slightly less important than the others. I'd support it if anybody wanted to implment this,

Agree that all those projects have Release Notes in the top nav. I'm just curious why?

collapsing remaining items into a dropdown

Overall, it seems to me many of those projects have the same problem of an awkward intermediate width where the nav bar suddenly develops a second line, followed quickly by the nav items being folded into the hamburger if the page gets even narrower. Rather than have a second way to collapse some items, I'd just set the width at which the total collapse happens to be wider to eliminate the awkward in between state.

Agree that all those projects have Release Notes in the top nav. I'm just curious why?

I think it's convention, large non-python projects also have it:

• https://code.visualstudio.com/ (they call it updates)
• https://kubernetes.io/ (versions)

My guess is 'cause it's functionally an advert page that's also very useful. Downstream developers, system admins, and folks deciding if they should update need the information to decide if they want to move and it's a log of how active/responsive the project is (lots of frequent fixes, shiny new features, etc).

Downstream developers, system admins, and folks deciding if they should update need the information to decide if they want to move and it's a log of how active/responsive the project is

For sure, the Release Notes are important. However, I consider the top navbar as a good way for folks to get to different parts of the docs when they are inside the docs at a page other than the front page, not as a signifier of importance. I'm skeptical folks a couple of layers deep often need to get to the Release Notes.

. I'm skeptical folks a couple of layers deep often need to get to the Release Notes.

I think it's more for decision makers who aren't gonna go a couple of layers deep to find it.

I think it's more for decision makers who aren't gonna go a couple of layers deep to find it.

That is my point - it only needs to be accessible on the front page, not to people who are a deeper in the docs.

That is my point - it only needs to be accessible on the front page, not to people who are a deeper in the docs.

which front page that's inaccessible from the rest of the docs?

https://matplotlib.org/stable/ (accessible via logo)
https://matplotlib.org/ (is in navbar and footer)

Granted, we could always go back to the old approach of having releases in a sidebar https://matplotlib.org/3.4.3/index.html

ETA: Also looking at that, releases should probably be posted to news (matplotlib/mpl-brochure-site#101)

Countering some of (my) argument, almost everything could just be on the start page. It's generally rare that you jump between the categories. So there's a little more behind it, not only the "accessible from everywhere" aspect. I think importance and covering all major topics also plays a role.

It's generally rare that you jump between the categories.

Except if you're trying to decide if you/your org should use matplotlib, and then I think you're explicitly jumping between to get a feel.

@QuLogic are you in charge of setting up the Plausible metrics? It would be very helpful to these discussions if there were a way to know how people navigate the website. Google Analytics used to provide this. It seems you need to set something up to make it happen in Plausible?