From 76d4456937c02a95af68678862429fde01f873da Mon Sep 17 00:00:00 2001 From: Ben Nathanson Date: Mon, 22 Jun 2020 13:10:02 -0400 Subject: [PATCH 1/4] DOC: Template/checklist for uniform NumPy tutorial style --- tutorial_style.ipynb | 208 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 208 insertions(+) create mode 100644 tutorial_style.ipynb diff --git a/tutorial_style.ipynb b/tutorial_style.ipynb new file mode 100644 index 00000000..8058eebb --- /dev/null +++ b/tutorial_style.ipynb @@ -0,0 +1,208 @@ +{ + "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", + "

Image credit: Daniele Procida's The documentation system

" + ] + }, + { + "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", + "- 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", + "At the end of the tutorial you'll put 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", + "Only the first word is capitalized (so not **Titles Are Lowercase**).\n", + "\n", + "\n", + "## What to say in \"What you'll learn\"\n", + "\n", + "Avoid abstraction. Rather than saying \"You'll learn about the quadratic equation,\" list skills (\"You'll be able to find the roots of a second-order polynomial.\")\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 a final 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", + "[Procida](https://documentation.divio.com/tutorials) writes:\n", + "\n", + "> Don’t explain anything the learner doesn’t need to know in order to complete the tutorial. \n", + "\n", + "Tutorial steps are clear and easy; production-grade, probably not. Don't stop to qualify; do this after the tutorial. \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 in a foreign country and want a feel for the terrain. The tutorial walks the reader through a solution, but the solution itself is subordinate. The journey is the destination. \n", + "\n", + "Unlike readers of a how-to, who know exactly 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", + "This \"tutorial\" itself, though presented in tutorial format, actually has a how-to goal and would normally be written as 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 ``, \n", + "replace the angle brackets with `<` and `>`.)" + ] + }, + { + "cell_type": "code", + "execution_count": 23, + "metadata": {}, + "outputs": [], + "source": [ + "#100/0" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "
\n", + " \n", + "---------------------------------------------------------------------------\n", + "ZeroDivisionError Traceback (most recent call last)\n", + "<ipython-input-10-bbe761e74a70> in <module>\n", + "----> 1 100/0\n", + "\n", + "ZeroDivisionError: division by zero\n", + "\n", + "
" + ] + }, + { + "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. The tutorial section can be followed with an **On your own** section for\n", + "the reader to practice their new skills.\n", + "\n", + "## In practice...\n", + "\n", + "- The asides that were avoided above can be dealt with in an **In practice...** section\n", + "\n", + "- You can, for instance, explain why the simple approach used in the tutorial is not used in practice, admit that you took advantage of a special case, and so on.\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 +} From 3e86a14991dabce57b0e8d9d039db6f5b5904bcb Mon Sep 17 00:00:00 2001 From: Ben Nathanson Date: Tue, 23 Jun 2020 11:55:20 -0400 Subject: [PATCH 2/4] DOC: Change word in PR #11 Say "second-degree" polynomials sted "second-order" in "What to say in 'What you'll learn." --- tutorial_style.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorial_style.ipynb b/tutorial_style.ipynb index 8058eebb..45471c4f 100644 --- a/tutorial_style.ipynb +++ b/tutorial_style.ipynb @@ -75,7 +75,7 @@ "\n", "## What to say in \"What you'll learn\"\n", "\n", - "Avoid abstraction. Rather than saying \"You'll learn about the quadratic equation,\" list skills (\"You'll be able to find the roots of a second-order polynomial.\")\n", + "Avoid abstraction. Rather than saying \"You'll learn about the quadratic equation,\" list skills (\"You'll be able to find the roots of a second-degree polynomial.\")\n", "\n", "\n", "## Why are \"What you'll do\" and \"What you'll learn\" different?\n", From 5757067970c5b4adfd5cdcd5b6fbc4c3884ebb25 Mon Sep 17 00:00:00 2001 From: Ben Nathanson Date: Wed, 12 Aug 2020 12:13:23 -0400 Subject: [PATCH 3/4] DOC: Add user profile in PR #11 Also small revisions throughout. --- tutorial_style.ipynb | 47 ++++++++++++++++++++++++++++---------------- 1 file changed, 30 insertions(+), 17 deletions(-) diff --git a/tutorial_style.ipynb b/tutorial_style.ipynb index 45471c4f..8ef591e2 100644 --- a/tutorial_style.ipynb +++ b/tutorial_style.ipynb @@ -49,6 +49,17 @@ "\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", @@ -60,36 +71,37 @@ "\n", "## After a horizontal rule, start your own headings\n", "\n", - "At the end of the tutorial you'll put another horizontal rule and return to standard headings.\n", + "Your tutoral 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", + "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", - "Only the first word is capitalized (so not **Titles Are Lowercase**).\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. Rather than saying \"You'll learn about the quadratic equation,\" list skills (\"You'll be able to find the roots of a second-degree polynomial.\")\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 a final 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", + "**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", - "[Procida](https://documentation.divio.com/tutorials) writes:\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", - "Tutorial steps are clear and easy; production-grade, probably not. Don't stop to qualify; do this after the tutorial. \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", @@ -106,11 +118,9 @@ "\n", "## Tutorials and how-to's -- similar but different\n", "\n", - "Tutorial readers are in a foreign country and want a feel for the terrain. The tutorial walks the reader through a solution, but the solution itself is subordinate. The journey is the destination. \n", - "\n", - "Unlike readers of a how-to, who know exactly 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", + "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", - "This \"tutorial\" itself, though presented in tutorial format, actually has a how-to goal and would normally be written as a how-to.\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", @@ -122,12 +132,12 @@ "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 ``, \n", - "replace the angle brackets with `<` and `>`.)" + "the angle brackets must be replaced by `<` and `>` as shown in the text cell markdown below.)" ] }, { "cell_type": "code", - "execution_count": 23, + "execution_count": 1, "metadata": {}, "outputs": [], "source": [ @@ -161,14 +171,17 @@ "\n", "## On your own\n", "\n", - "Close the tutorial section with a horizontal rule. The tutorial section can be followed with an **On your own** section for\n", - "the reader to practice their new skills.\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 asides that were avoided above can be dealt with in an **In practice...** section\n", + "- The fine print that you avoided can go in this section.\n", + "\n", + "\n", "\n", - "- You can, for instance, explain why the simple approach used in the tutorial is not used in practice, admit that you took advantage of a special case, and so on.\n", + "- Don't just say it's usually done another way; explain why. \n", " \n", "\n", "## Further reading\n", From 182e37e7d3cb448fc6a18f0be1981c5b247bbb17 Mon Sep 17 00:00:00 2001 From: Ben Nathanson Date: Wed, 12 Aug 2020 13:33:30 -0400 Subject: [PATCH 4/4] DOC: Fix typo in PR #11 --- tutorial_style.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorial_style.ipynb b/tutorial_style.ipynb index 8ef591e2..1442152f 100644 --- a/tutorial_style.ipynb +++ b/tutorial_style.ipynb @@ -71,7 +71,7 @@ "\n", "## After a horizontal rule, start your own headings\n", "\n", - "Your tutoral 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", + "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",