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", + "- 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 ` \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",
+ "