DOC: How-to guide for how-tos

[bjnath]

Writing guidelines for how-to docs.

[melissawm]

nit: I had no idea what prefatory meant (loved learning about it!), maybe change it to a simpler word for the benefit of non-native English speakers?

[8bitmp3]

I really like this How-to guide for how-tos @bjnath - thank you!

As @melissawm said, maybe change it to a simpler word. What do you think about using "introductory"? (Ref: https://developers.google.com/style/translation#be-inclusive)

Cheers!

[melissawm]

@bjnath thanks, I liked the guide and it does make it much simpler to organize thoughts around how-tos. I can see what you mean in #15 . I do think I'd like to see some discussion here to see if more people agree or if we're looking for something different for how-tos.

[melissawm]

Maybe @rossbar or @mattip would like to take a look?

[melissawm]

As discussed in the Documentation Team meeting, I'd like to merge this. However, this guide (just like the I/O How-to #15 ) needs to be in notebook format, which would make it easier for people to browse using Binder, for example.

[bjnath]

Something we haven't discussed: While notebooks are perfect for tutorials, they're wrong for how-tos.

Tutorials are meant to be executable, so notebooks are great for them.

How-tos aren't meant to be executable. You can see that in #15 -- there's nothing to execute there. It's just names of commands and pointers to other docs.

Thus there's no value in putting a how-to in a notebook. It would consist of a single text cell.

Two conclusions:

1. If how-tos aren't notebooks, they probably belong not in this repo but with the main Sphinx docs.

2. If people nonetheless see a need for how-tos to be notebooks, it suggests we haven't converged on what a how-to is, and it's probably too soon to merge.

[melissawm]

This makes sense. My thinking was that writing them in notebooks might make the barrier of entry a little smaller for people. However, if you're writing a how-to, maybe that barrier is not so relevant. In that case, this how-to should be submitted to the main repo instead of here.

[bjnath]

Per discussion, the content is now on the Sphinx pages: https://numpy.org/devdocs/user/how-to-how-to.html