Thanks @rgommers 👍 @melissawm @rossbar Should we start exploring this?

The Pandas docs layout, as @rgommers pointed out, looks like this:

I wonder if the Sphinx theme supports a nav bar (similar to what we've got now) that you can include on the left-hand side:

If not, some of the links could go above or below the "large blocks":

More inspiration where the layouts include nav bars + "large blocks":

1. https://www.tensorflow.org/tutorials

2. https://pytorch.org/tutorials/

I wonder if the Sphinx theme supports a nav bar (similar to what we've got now) that you can include on the left-hand side:
image

We don't need those links, they're very messy and there's little point in preserving them.

If not, some of the links could go above or below the "large blocks":

I'd suggest to start with the exact Pandas layout (including links like "mailing list" in the same format), and then see if we are missing anything. If each of the links currently on the front page has a natural place below one of the tiles, then we're all good. If not, we'll find a place for it. On first inspection, I think everything fits nicely.

I love this idea. Maybe @MarsBarLee can chip in, too, from the design point of view. But I agree with @rgommers , we can start with the Pandas layout and see if we miss anything.

Here's my mockup:

Most of the text is taken straight from the pandas' page, just modified to NumPy. However, I've changed 'Developer guide' to 'Contributor's Guide' to emphasize the non-code contributions people can make.

The text above the blocks is from the What is Numpy? page.

This does make a nice 4 blocks, but when I referred to the pandas page, their blocks lead to more links. Here's my thoughts on how we can arrange ours:

Getting Started: On the pandas website, this leads to a landing page with a few different guides, such as different installations, introduction tutorials and for people familiar with R, SQL, etc.
We could make a similar landing page with NumPy installation, absolute beginner's guide, F2PY user guide, NumPy for MATLAB users and quickstart ("Aimed at domain experts or people migrating to NumPy").

User Guide: Another landing page for NumPy tutorials, how-tos and fundamentals.

API Reference: NumPy Reference page.

Contributor's Guide: Contributing to NumPy page.

I'm not sure where the other links, such as Building From Source would go.

@MarsBarLee

@MarsBarLee I'd personally suggest to minimize the number of clicks to 3 max before a user can find a relevant tutorial/guide. I read about this somewhere... maybe it was about AirBnb approaches its UX.

Most of the text is taken straight from the pandas' page, just modified to NumPy.

Makes sense - no need to rework things that are already well thought out:)

However, I've changed 'Developer guide' to 'Contributor's Guide' to emphasize the non-code contributions people can make.

Good idea!

User Guide: Another landing page for NumPy tutorials, how-tos and fundamentals.

I like all your four sections. The one thing I would add is: something like the "quickstart" can be both under "Getting Started" and under "User Guide". That makes navigation easier, there's no reason we have to choose where it goes cause it fits under both categories.

I'd personally suggest to minimize the number of clicks to 3 max before a user can find a relevant tutorial/guide.

Agreed. That's how I read @MarsBarLee's plan already. E.g. User guide would have the direct links to tutorials, howto's and fundamentals. No need for another level of almost-empty pages like https://numpy.org/devdocs/user/howtos_index.html

Hi all, this is a mockup of the Getting Started page.

Following pandas example, I've simplified the conda commands from the installation page from

# Best practice, use an environment rather than install in the base env
conda create -n my-env
conda activate my-env
# If you want to install from conda-forge
conda config --env --add channels conda-forge
# The actual install command
conda install numpy

to

conda install numpy

I've also moved up the section on virtual environments to reduce repetition. The full installation commands can still be seen in the installation page.

The descriptions for the Starting Guides and 'Coming from...' are definitely still open for changes. I've pulled the descriptions from their respective pages, kept some of the same wording and summarized the rest. If there's something wrong with the terminology, let me know!

Next up is making a mockup of the User Guide section. Eventually I'll put all the mockups on a clickable online prototype, so we can see how everything is linked together and keep to the '3 clicks max' rule.

matplotlib may take offense at being mistaken for Matlab:) I suggest to just use regular text for Matlab, not a logo (that can have copyright issues). Other than that this looks quite good.

Following pandas example, I've simplified the conda commands from the installation page from

I think our instructions are better - we added those on purpose. Users who need this kind of getting started info really need to be taught this.

This looks great, @MarsBarLee !

A few points:

• there is an extra period at the end of NumPy can be installed via pip:
• For f2py, I'd suggest the last sentence to read "Learn about using f2py to wrap your code" or something similar. I don't think we should mention signature files here.

Thanks!

@melissawm Is there a PR in the works for this?

Not yet - @MarsBarLee is working on a mockup first, and then she will tackle the actual implementation. But we're working on it!

Hi all, this is a link to the interactive prototype.

This prototype exists as a low-cost, quick and iterative overview of how several pages could look and ‘feel’ together.

If you have a suggestion, if possible, put in your experience as context. For example- ‘As an experienced NumPy user, I would like to quickly reach the Reference. Could we put a link to the Reference in the left navigation bar?’

• In UI/UX terms, this is a ‘user profile’ or ‘user story’. It helps us understand and meet the needs of different users
• You can leave comments on Github instead of on Penpot (the prototyping platform)

Here's answers to some questions

• Some pages are rougher/don't look at nice as others or missing links- that's also good feedback! I'm still updating some pages but as a whole I think this can be released for feedback
• There is no direct ‘translation’ from prototype to code. Implementation will be through the current Sphinx theme
• The advantage of prototyping is that instead of PRs that updates one page at a time, we can reach a consensus before putting a line of code, saving time down the road
• 'WYSIWYG'- no need for people download a branch and spin up a local instance. We can click this link and see immediately
• This prototype is continually updated

Hey there @MarsBarLee! I know this is a delayed comment, but I've been thinking a little about this since you brought it up at the last NumPy docs meeting.

Most of this makes sense to me. My only note is that I find it confusing when the same image is used for different guides (even though they are on different pages). The only one I noticed was that "Getting Started" on the landing page and "Absolute Beginner's Guide" both use the running person.

Minor nit about the Getting started design --> For F2PY though, the documentation doesn't really address (nor should it) moving from Fortran to NumPy.

I see the F2PY User and Development Guide to be at the same conceptual level as the User Guide or API Reference. Currently we have:

• User Guide
  • F2PY User Guide and Reference Guide

I'd suggest something along the lines of -->

• User
  • Blah blah
• F2PY
• API Docs
• Blah blah

Also I can't seem to access the prototype @MarsBarLee but it seems super neat.

Hi @isabela-pf and @HaoZeke, thank you for the feedback on re-organizing the content! I think for now, I'll complete the initial page layout that was laid out in the interactive prototype. The PR for that is #19756. Once that is done, I'll make a new PR for re-organizing the content.

I've also updated the prototype link- thanks Rohit for letting me know. A version update of the prototyping software changed the link.

Hi folks, I think this is finalized for now, so I'm closing. Feel free to open new issues if you have further suggestions for improvements. Thanks!