Guidelines for NumPy tutorials

classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|

Guidelines for NumPy tutorials

Ben Nathanson
I've submitted PR #11 in the new numpy-tutorials repo
(https://github.com/numpy/numpy-tutorials/pull/11) to provide a
checklist and standard style for writing tutorials.

Added tutorial content is an objective of NEP 44. We're expecting part
of the content to come from new contributors (for instance, through
Ryan Cooper's generous offer to get his students involved,
https://mail.python.org/pipermail/numpy-discussion/2020-May/080715.htmll).
The PR will provide a guide for all contributors to work from.

While "tutorial" is often used broadly for introductory material, here
it is closely defined: a multistep participatory walkthrough for a
user new to NumPy.

This is the meaning of "tutorial" in NEP 44; it was originally
distinguished from other kinds of documentation by Daniele Procida
(https://documentation.divio.com/tutorials/).

One goal of the PR, in fact, is to make sure the tutorial stays a
tutorial and doesn't mission-creep into other kinds of introductory
documentation. Procida's insight is that mission creep like this leads
to failed docs.

At today's docs meeting it was suggested that the PR be announced on
the mailing list for possible further comment.
_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion
Reply | Threaded
Open this post in threaded view
|

Re: Guidelines for NumPy tutorials

Melissa Mendonça
Hi all,

Thanks for the PR, Ben.

Note that this is in the numpy-tutorials repo, which is a new repo created to specifically host Jupyter notebook tutorials for NumPy users. It is still not in its final form.

One of the questions around this PR is where this style guide should live: in the main documentation or in the numpy-tutorials repo?

If you have thoughts on this, please share.

Best,

- Melissa

On Mon, Jun 22, 2020 at 3:44 PM Ben Nathanson <[hidden email]> wrote:
I've submitted PR #11 in the new numpy-tutorials repo
(https://github.com/numpy/numpy-tutorials/pull/11) to provide a
checklist and standard style for writing tutorials.

Added tutorial content is an objective of NEP 44. We're expecting part
of the content to come from new contributors (for instance, through
Ryan Cooper's generous offer to get his students involved,
https://mail.python.org/pipermail/numpy-discussion/2020-May/080715.htmll).
The PR will provide a guide for all contributors to work from.

While "tutorial" is often used broadly for introductory material, here
it is closely defined: a multistep participatory walkthrough for a
user new to NumPy.

This is the meaning of "tutorial" in NEP 44; it was originally
distinguished from other kinds of documentation by Daniele Procida
(https://documentation.divio.com/tutorials/).

One goal of the PR, in fact, is to make sure the tutorial stays a
tutorial and doesn't mission-creep into other kinds of introductory
documentation. Procida's insight is that mission creep like this leads
to failed docs.

At today's docs meeting it was suggested that the PR be announced on
the mailing list for possible further comment.
_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion

_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion