Thanks to visit codestin.com
Credit goes to github.com

Skip to content

DOC: Discussion - How to organize tutorials #19191

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
melissawm opened this issue Jun 7, 2021 · 3 comments Β· Fixed by #19418
Closed

DOC: Discussion - How to organize tutorials #19191

melissawm opened this issue Jun 7, 2021 · 3 comments Β· Fixed by #19418

Comments

@melissawm
Copy link
Member

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

@melissawm melissawm changed the title Discussion: How to organize tutorials [DOC] Discussion: How to organize tutorials Jun 7, 2021
@melissawm melissawm changed the title [DOC] Discussion: How to organize tutorials DOC: Discussion - How to organize tutorials Jun 7, 2021
@rgommers
Copy link
Member

rgommers commented Jun 8, 2021

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
Copy link
Contributor

MarsBarLee commented Jun 21, 2021

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
Copy link
Member Author

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants