DOC: Discussion - How to organize tutorials

[melissawm]

Documentation

Now that https://numpy.org/numpy-tutorials/ is deployed, we need to decide how to organize our internal documentation.

Currently, this page is also called NumPy Tutorials. The two tutorials listed there are also available as Jupyter Notebooks from the separate numpy-tutorials repo.

In our docs team meetings, we have discussed two possibilities:

1. Keeping two sets of tutorials. This would allow us to separate the contents into in-depth guides about NumPy features (in the main sphinx docs) and general tutorials with applications of NumPy in other domains (in the numpy-tutorials repo). In this case, the tutorials section in the main docs would have to be renamed; one suggestion is "NumPy Guides" or similar.
2. Only keeping the numpy-tutorials repo, making the sphinx tutorials page point to the rendered numpy-tutorials site and adding any new content there.

It would be nice to have further input from the community so we can reach a solution. If you have other ideas, please feel free to let us know!

cc @rossbar @rgommers @cooperrc @8bitmp3

[rgommers]

I'm in favor of (2). Duplicated content doesn't make sense. Having a clear split between User Guide and numpy-tutorials makes sense to me. User Guide focus more on individual NumPy features and how to use them, while Tutorials are more application-focused and teach NumPy usage in the process.

[MarsBarLee]

My NumPy Docs page redesign proposal would change the main docs/sphinx front page, Getting Started and User Guide page. I'm also in favor 2). With sphinx tutorials page, I didn't include it in my redesign at first since there was so sparse and I wasn't sure how to/if needed to arrange 2 items.

With 2), the main docs/sphinx pages would still act as the first entryway, and even if a user ultimately needs numpy-tutorials, the redesign will help them get there.

Redesigned Docs front page:

• Getting Started
• User Guide
• API Reference
• Contributor's Guide

This flow could like look like this: Docs front page -> User Guide page -> Tutorials, which would link to numpy-tutorials.

Tutorials could be linked from multiple pages:
Docs front page -> Getting Started -> Tutorials

Tutorials could also be linked on the front page, but I think adding more categories brings up the re-occurring issue of similar sounding words for different concepts, which may be confusing.

Redesigned Docs front page:

• Getting Started
• User Guide
• API Reference
• Tutorials
• Contributor's Guide

Maybe the description text under the Tutorials heading here could be
Tutorials
Step-by-step tutorials written as Jupyter notebooks. These notebooks can be launched in Binder, so you can interact with the examples as you follow along.

This is getting long, so perhaps a visual prototype of what I'm talking about would help, haha.

[melissawm]

PR above has my proposal for now. Once the new landing page is here, we can reorganize if needed. Thanks!