General

I agree that the document structure, navigation and layout could be improved. We need to be careful though:

optimally here I'd move the "open an issue" content into the triage document

IMHO that would be much worse. The current "Submitting a bug report" section is a very focused description on half a screen. Tugging that under the "Triaging" topic, that is much more complex and multiple screens of content, would be very scary for first-time visitors.

Specific to this PR

The purpose of the buttons is to give a quick navigation for often needed actions of (first-time?) visitors to the page: Somebody wants to ask for a feature and goes to the "development" site. The button "Request a feature" directly picks up on that intention. We should assume that such a person does not know much about devlopment processes - otherwise they might have directly gone to github via the menu bar. For such people "Open an issue" is less clear than "Request a feature". Therefore, I oppose merging bug and feature buttons.

While I acknowledge that "Setup environment" is a task that you need often, I assume that is rarely the case for the average visitor of the site. "Setup environment" is a technical detail that requires already knowledge on the overall development process. Direct access is only relevant for recurring contributors. A first time contributor should go through "Contribute code" or "Write documentation", which are at the same time more focussed on the intent and have a complete description of all aspects needed to get started.
Therefore "Setup environment" is of use only for maybe 10-20 people, while distracting all others.

The current "Submitting a bug report" section is a very focused description on half a screen. Tugging that under the "Triaging" topic, that is much more complex and multiple screens of content, would be very scary for first-time visitors.

I'd move the section and use the button to anchor so that the link would directly go to a section "submitting a bug report". I don't think it'll be scary as it basically puts the what with the why, and my reasoning is that moving like with like will help us keep things more in sync.

Therefore "Setup environment" is of use only for maybe 10-20 people, while distracting all others.

I made this PR cause I was walking a contributor through contributing and it was hard to find, and this came up when I was running a sprint & also found the information really hard to find. Like yes they should go through the other things first, but my experience has been that folks more often then not start at setting up the dev environment and then work backwards to the specifics of code and docs. Especially if they've contributed to other projects before.

Switched it up and now am messing around with wrapping the set up dev environment specific stuff in a card and creating implicit "contribute, develop, maintain" groupings, but that takes a number of rerun cycles so pitching to draft while I sort out how to get things working.

The triage one is kinda weird cause it's half process and half how to contribute and I think reorging that doc and then sorting here would make sense. I also would show the contributing second levels and not the first but I don't know how to do that.

screenshot: setup button

Closed in error (fat fingers) sorry.

something in the direction of

screenshot: Version 0 of cards

with the intention that the coding guide cards will be expanded/refined when those documents get consolidated/reorganized.

@timhoffm reworked it so that the buttons stay the same but I've tried to improve the roadmapping so that's more clear where new contributors should start/go & also make the page more skimmable.

Screenshot of docs that are building

I'm a little opinionated here about which sections I link on this landing page 'cause I'm trying for not overwhelming. I think some of the titles that appear redundant point to places where we can consolidate information, and that if we consolidate then we can expand the listings on this page. Basically I think most of the wonkyness left here is due to underlying information architecture issues.

Unfortunately the CI doc build is currently broken, and I'd like to have a closer look once it's fixed. Just from the screenshot though, I really like this change: it still has the "where do I even start" type stuff right at the top, but the panels make it a lot easier for someone who already knows what change they want to make to find the relevant information. I like the clear separation between code and doc changes.

When I first contributed in Matplotlib, I already had some experience in other OSS projects. So my first question was "how do I create an environment and build from source" (now clearly linked under setup). Next question was "what do I need to know that is specific to this project" which I think is mostly contained in the PR guidelines.

😍

Unfortunately the CI doc build is currently broken, and I'd like to have a closer look once it's fixed

The page still built https://output.circle-artifacts.com/output/job/8148cfa1-27bd-4b08-9a24-9eee9d2f3234/artifacts/0/doc/build/html/devel/index.html

chatted w/ @melissawm about maybe putting in a codespaces link in the top batch. My reasoning is that folks who know they need to install will find those instructions. Not quite sure what the copy should be

contribute section w/ clickable cards instead of buttons

Yeah so I agree on not loving where the buttons are landing, but honestly like the way I think it should be fixed is to either:

• rewrite those sections of the contributing guide to be more "what is this" like bugs & features
• consolidate away those paragraphs into the tops of the code and docs pages so that they have their intros - and I'd do the same on the triage page, and then on the contributing page link out or include those paragraphs

But I think either way, a good fix is gonna be another chunk of PR back and forth that I don't think I have time for right now.

Eta: I'd still leave em at the top as quick access - I'm the one who changed where the docs button was pointing to cause I couldn't find build -> and like I think the document page needs some organization so that information is easier to find before I incorporate it into this page.

OK agreed, let’s leave those buttons for now. Can’t fix everything at once and this PR already gives us a significant improvement.

I’m happy to merge assuming the next round of CircleCI passes.

Let me know if you’d prefer to squash the commits first.

Thanks @rcomer, as much as I may be stepping on a landmine my bias is to leave this for a day or so in case anyone has any major objections since it's a pretty large UX overhaul

I really like the box. Optional: Add headings to both columns as an additional guide/scope:

Hmm, maybe though I dunno how common FAQ is for the generation younger than me...maybe adding a lightish background to the cards will make it more clear they're buttons? I don't think action is descriptive enough to be instructive.

What I'd love but dunno how to do is to get the card headings to show up as subheadings in the "on this page" sidebar ,

Eta: my other concern w/ FAQ is that it may dissuade folks from asking those questions in a "like here we answered it OK" when we're aiming for the exact opposite of trying to invite more questions.

I would try very hard to restrict myself to doing this as TOC entries, and I would try and make it a similar order as the docs themselves. Most of this could be done with level-2 TOCs and then they would show up properly in the left sidebar. If that means reorganizing some of the underlying pages that would be fine. I'm somewhat concerned with repetition and having a top-level page that doesn't look like the contents, or the left or right bars.

I would try very hard to restrict myself to doing this as TOC entries, and I would try and make it a similar order as the docs

I did and it doesn't work b/c the underlying architecture of the docs is far as I can tell a patchwork of what somebody thought each individual doc needed w/o looking at the larger collection of docs. There's just so much duplication that makes more sense as cross links and part of what I'm trying to do here is put like w/ like so that later on I can reorg and smooth out the links. I just really really don't have the time management skills to go down that rabbit hole right now - I spent way too much time on this as is.

ETA: to be clear, the thing that I think based on my initial forays is that doing this well will take a lot of time - I worry doing it quickly will create more of a mess down the line.

I am concerned about adding yet another structure on top of the already messy structure, but certainly not enough to block. Perhaps if this goes in, it should be accompanied by an issue explaining what needs to be fixed.

it should be accompanied by an issue explaining what needs to be fixed

#26196 <- there's a reason I keep wanting this as part of a grant

Let's merge this as an improvement. I think we need to be a bit more aggressive in allowing moribund pages to be revamped, even if the revamp is not particularly to our personal taste. Follow-up PRs are most welcome.