Skip to content

DOC: Template/checklist for uniform NumPy tutorial style #11

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.

Sign up for GitHub

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

Merged
merged 4 commits into from
Aug 20, 2020
Merged

DOC: Template/checklist for uniform NumPy tutorial style #11

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
76d4456
DOC: Template/checklist for uniform NumPy tutorial style
bjnath Jun 22, 2020
3e86a14
DOC: Change word in PR #11
bjnath Jun 23, 2020
5757067
DOC: Add user profile in PR #11
bjnath Aug 12, 2020
182e37e
DOC: Fix typo in PR #11
bjnath Aug 12, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
221 changes: 221 additions & 0 deletions tutorial_style.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,221 @@
{
"cells": [
{
"cell_type": "markdown",
"metadata": {
"colab_type": "text",
"id": "rKyNp_FWPuFL"
},
"source": [
"# Learn to write a NumPy tutorial\n",
"***"
]
},
{
"cell_type": "markdown",
"metadata": {
"colab_type": "text",
"id": "8VpdPmoZkR7_"
},
"source": [
"![image](https://documentation.divio.com/_images/overview.png)\n",
"<p style=\"text-align:right;font-style:italic;\">Image credit: Daniele Procida's <a href=\"https://documentation.divio.com/\">The documentation system</a></p>"
]
},
{
"cell_type": "markdown",
"metadata": {
"colab_type": "text",
"id": "WICNDncaP8k_"
},
"source": [
"## What you'll do\n",
"\n",
"Guided by a template, you'll write a NumPy tutorial.\n",
"\n",
"## What you'll learn\n",
"\n",
"- You'll be able to craft a tutorial that follows a standard format and reflects good teaching practice.\n",
"\n",
"- You'll learn the three standard headings that open a NumPy tutorial -- **What you'll do,** **What you'll learn,** and **What you'll need** -- and some optional headings for the bottom -- **On your own,** **In practice,** **Further reading.**\n",
"\n",
"- You'll know what makes **What you'll learn** different from **What you'll do.**\n",
"\n",
"- You'll be able to distinguish a **tutorial** from a **how-to**.\n",
"\n",
"- You'll learn what not to put in a **What you'll learn** section.\n",
"\n",
"## What you'll need\n",
"\n",
"- This template.\n",
"\n",
"- A portrait of your intended reader. \n",
" - Just as schools list prerequisites for higher-level courses, you can assume readers know some things (which you must list, as noted in the next bullet). Overexplaining bogs down the tutorial and obscures the main points.\n",
" - But also put yourself in the reader's place and consider what to explain along the way.\n",
" \n",
" \n",
"- \"What you'll need\" is a list of:\n",
"\n",
" - packages that must be present on the user's machine before they begin. Don't include `numpy`.\n",
" - what you assumed the reader knew in the bullet above. Don't say `Python`; `familiarity with Python iterators` is fine.\n",
"\n",
"\n",
"- Informality and enthusiasm. Imagine your reader not out in the audience but next to you.\n",
"\n",
"- Willingness to write incomplete sentences for the **What you'll need** bullets. They don't begin with the words \"You'll need.\"\n",
"\n",
"- **Not** required are native English skills. Others can help.\n",
"\n",
"\n",
"***\n",
"\n",
"## After a horizontal rule, start your own headings\n",
"\n",
"Your tutorial steps begin here, using headings of your choice. At the end of the tutorial you'll place another horizontal rule and return to standard headings.\n",
"\n",
"\n",
"## Titles have verbs\n",
"\n",
"In general, include a verb in the title; thus **Learn to write a NumPy tutorial** rather than \"Rules for NumPy tutorials.\" Consider putting verbs in the headings as well.\n",
"\n",
"\n",
"## Titles are lowercase\n",
"\n",
"Capitalize the first word, and after that only words that are ordinarily capitalized (so not \"Titles Are Lowercase\").\n",
"\n",
"\n",
"## What to say in \"What you'll learn\"\n",
"\n",
"Avoid abstraction. \"About\" is a tipoff: Rather than writing \"You'll learn about NumPy I/O,\" write \"You'll learn how to read a comma-delimited text file into a NumPy array.\"\n",
"\n",
"\n",
"## Why are \"What you'll do\" and \"What you'll learn\" different?\n",
"\n",
"**What you'll do** is typically one sentence listing an end product: \"You'll bake a cake.\" This makes the endpoint clear. **What you'll learn** lists the payoffs, and there may be many: \"You'll learn to follow a recipe. You'll get practice measuring ingredients. You'll learn how to tell when a cake is ready to come out of the oven.\" \n",
"\n",
"\n",
"## Avoid asides\n",
"\n",
"As explained by master documentation writer [Daniele Procida](https://documentation.divio.com/tutorials):\n",
"\n",
"> Don’t explain anything the learner doesn’t need to know in order to complete the tutorial. \n",
"\n",
"Because tutorial steps are chosen to be clear and easy, they may fall short of\n",
"production-grade. Yes, you should share this, but not during the tutorial, which should be straightforward and assured. The `In practice` section is the place for details, exceptions, alternatives, and similar fine print.\n",
"\n",
"\n",
"## Use plots and illustrations\n",
"\n",
"Figures are a double win; they amplify your points and make the page inviting. Like English skills, artistic skills (or graphic-toolset skills) aren't required. Even if you only scan a hand illustration, somebody can polish it.\n",
"\n",
"An illustration below the title, even if it's only decorative, makes your page distinctive.\n",
"\n",
"\n",
"## Use real datasets when possible\n",
"\n",
"Readers are likelier to be engaged by a real use case. Be sure you have rights to the data.\n",
"\n",
"\n",
"## Tutorials and how-to's -- similar but different\n",
"\n",
"Tutorial readers are out-of-towners who want a feel for the place. Pick any single destination and explain sights along the way.\n",
"\n",
"Unlike how-to readers, who know what they need, tutorial readers don't know what it is they don't know. So while tutorials need headings like **What you'll do** and **What you'll learn**, these headings would never appear in a how-to.\n",
"\n",
"## Make use of the Google doc style guide\n",
"\n",
"NumPy docs follow the [Google developer documentation style guide](https://developers.google.com/style/). In addition to providing answers to recurring questions (\"crossreference\" or \"cross-reference\"?) the guide is filled with suggestions that will strengthen your doc writing.\n",
"\n",
"## The notebook must be fully executable\n",
"\n",
"`Run all cells` should execute all cells to the bottom of the file. If you're demonstrating a bad expression and want to show the traceback, comment\n",
"the expression and put the traceback in a text cell.\n",
"\n",
"(Note that triple backquotes won't be enough for a traceback that contains `<text inside angle brackets>`, \n",
"the angle brackets must be replaced by `&lt;` and `&gt;` as shown in the text cell markdown below.)"
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [],
"source": [
"#100/0"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"<div style=\"background-color:#fcdcdc\">\n",
"<code style=\"background-color:#fcdcdc;font-size:90%\"> \n",
"---------------------------------------------------------------------------\n",
"ZeroDivisionError Traceback (most recent call last)\n",
"&lt;ipython-input-10-bbe761e74a70&gt; in &lt;module&gt;\n",
"----> 1 100/0\n",
"\n",
"ZeroDivisionError: division by zero\n",
"</code>\n",
"</div>"
]
},
{
"cell_type": "markdown",
"metadata": {
"colab_type": "text",
"id": "WICNDncaP8k_"
},
"source": [
"***\n",
"\n",
"## On your own\n",
"\n",
"Close the tutorial section with a horizontal rule. You're free to take any direction now, but here are three suggested sections.\n",
"\n",
"In an optional `On your own` section, you can offer an assignment for readers to exercise their new skills. If it's a question with an answer, provide it -- perhaps in a footnote to keep it from being a spoiler.\n",
"\n",
"## In practice...\n",
"\n",
"- The fine print that you avoided can go in this section.\n",
"\n",
"\n",
"\n",
"- Don't just say it's usually done another way; explain why. \n",
" \n",
"\n",
"## Further reading\n",
"\n",
"- Ideally, rather than giving bare links, **Further reading** describes the references: [The Documentation System](https://documentation.divio.com/) is the inspiration for this tutorial, and describes three other kinds of documentation.\n",
"- The Google guide is long; there's also [a summary](https://developers.google.com/style/highlights?hl=pt-br).\n",
"- NumPy's website includes a [documentation how-to](https://numpy.org/devdocs/dev/howto-docs.html)."
]
}
],
"metadata": {
"colab": {
"include_colab_link": true,
"name": "tutorial-svd.ipynb",
"provenance": []
},
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.8.3"
}
},
"nbformat": 4,
"nbformat_minor": 4
}