DOC: How-to guide for how-tos #16
Conversation
Writing guidelines for how-to docs.
how_to_how_to.md
Outdated
|
|
||
| * Three miles, take a right at Hayseed Road, follow the signs. | ||
|
|
||
| If the information is already in the docs, link to it -- don't repeat it. If the API doc is sufficiently clear, link directly to it after you've given the prefatory information ("Three miles, take a right"). |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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!
Replaced the word "prefatory" with a simpler paraphrase.
|
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. |
|
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:
|
|
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. |
|
Per discussion, the content is now on the Sphinx pages: https://numpy.org/devdocs/user/how-to-how-to.html |
Writing guidelines for how-to docs.