Skip to content

Commit fa82434

Browse files
melissawmmelissawm
authored
Merge pull request #11 from bjnath/tutorials-guide
DOC: Template/checklist for uniform NumPy tutorial style
2 parents 4772649 + 182e37e commit fa82434

File tree

1 file changed

+221
-0
lines changed

1 file changed

+221
-0
lines changed

‎tutorial_style.ipynb

+221
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {
6+
"colab_type": "text",
7+
"id": "rKyNp_FWPuFL"
8+
},
9+
"source": [
10+
"# Learn to write a NumPy tutorial\n",
11+
"***"
12+
]
13+
},
14+
{
15+
"cell_type": "markdown",
16+
"metadata": {
17+
"colab_type": "text",
18+
"id": "8VpdPmoZkR7_"
19+
},
20+
"source": [
21+
"![image](https://documentation.divio.com/_images/overview.png)\n",
22+
"<p style=\"text-align:right;font-style:italic;\">Image credit: Daniele Procida's <a href=\"https://documentation.divio.com/\">The documentation system</a></p>"
23+
]
24+
},
25+
{
26+
"cell_type": "markdown",
27+
"metadata": {
28+
"colab_type": "text",
29+
"id": "WICNDncaP8k_"
30+
},
31+
"source": [
32+
"## What you'll do\n",
33+
"\n",
34+
"Guided by a template, you'll write a NumPy tutorial.\n",
35+
"\n",
36+
"## What you'll learn\n",
37+
"\n",
38+
"- You'll be able to craft a tutorial that follows a standard format and reflects good teaching practice.\n",
39+
"\n",
40+
"- 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",
41+
"\n",
42+
"- You'll know what makes **What you'll learn** different from **What you'll do.**\n",
43+
"\n",
44+
"- You'll be able to distinguish a **tutorial** from a **how-to**.\n",
45+
"\n",
46+
"- You'll learn what not to put in a **What you'll learn** section.\n",
47+
"\n",
48+
"## What you'll need\n",
49+
"\n",
50+
"- This template.\n",
51+
"\n",
52+
"- A portrait of your intended reader. \n",
53+
" - 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",
54+
" - But also put yourself in the reader's place and consider what to explain along the way.\n",
55+
" \n",
56+
" \n",
57+
"- \"What you'll need\" is a list of:\n",
58+
"\n",
59+
" - packages that must be present on the user's machine before they begin. Don't include `numpy`.\n",
60+
" - what you assumed the reader knew in the bullet above. Don't say `Python`; `familiarity with Python iterators` is fine.\n",
61+
"\n",
62+
"\n",
63+
"- Informality and enthusiasm. Imagine your reader not out in the audience but next to you.\n",
64+
"\n",
65+
"- Willingness to write incomplete sentences for the **What you'll need** bullets. They don't begin with the words \"You'll need.\"\n",
66+
"\n",
67+
"- **Not** required are native English skills. Others can help.\n",
68+
"\n",
69+
"\n",
70+
"***\n",
71+
"\n",
72+
"## After a horizontal rule, start your own headings\n",
73+
"\n",
74+
"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",
75+
"\n",
76+
"\n",
77+
"## Titles have verbs\n",
78+
"\n",
79+
"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",
80+
"\n",
81+
"\n",
82+
"## Titles are lowercase\n",
83+
"\n",
84+
"Capitalize the first word, and after that only words that are ordinarily capitalized (so not \"Titles Are Lowercase\").\n",
85+
"\n",
86+
"\n",
87+
"## What to say in \"What you'll learn\"\n",
88+
"\n",
89+
"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",
90+
"\n",
91+
"\n",
92+
"## Why are \"What you'll do\" and \"What you'll learn\" different?\n",
93+
"\n",
94+
"**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",
95+
"\n",
96+
"\n",
97+
"## Avoid asides\n",
98+
"\n",
99+
"As explained by master documentation writer [Daniele Procida](https://documentation.divio.com/tutorials):\n",
100+
"\n",
101+
"> Don’t explain anything the learner doesn’t need to know in order to complete the tutorial. \n",
102+
"\n",
103+
"Because tutorial steps are chosen to be clear and easy, they may fall short of\n",
104+
"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",
105+
"\n",
106+
"\n",
107+
"## Use plots and illustrations\n",
108+
"\n",
109+
"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",
110+
"\n",
111+
"An illustration below the title, even if it's only decorative, makes your page distinctive.\n",
112+
"\n",
113+
"\n",
114+
"## Use real datasets when possible\n",
115+
"\n",
116+
"Readers are likelier to be engaged by a real use case. Be sure you have rights to the data.\n",
117+
"\n",
118+
"\n",
119+
"## Tutorials and how-to's -- similar but different\n",
120+
"\n",
121+
"Tutorial readers are out-of-towners who want a feel for the place. Pick any single destination and explain sights along the way.\n",
122+
"\n",
123+
"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",
124+
"\n",
125+
"## Make use of the Google doc style guide\n",
126+
"\n",
127+
"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",
128+
"\n",
129+
"## The notebook must be fully executable\n",
130+
"\n",
131+
"`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",
132+
"the expression and put the traceback in a text cell.\n",
133+
"\n",
134+
"(Note that triple backquotes won't be enough for a traceback that contains `<text inside angle brackets>`, \n",
135+
"the angle brackets must be replaced by `&lt;` and `&gt;` as shown in the text cell markdown below.)"
136+
]
137+
},
138+
{
139+
"cell_type": "code",
140+
"execution_count": 1,
141+
"metadata": {},
142+
"outputs": [],
143+
"source": [
144+
"#100/0"
145+
]
146+
},
147+
{
148+
"cell_type": "markdown",
149+
"metadata": {},
150+
"source": [
151+
"<div style=\"background-color:#fcdcdc\">\n",
152+
"<code style=\"background-color:#fcdcdc;font-size:90%\"> \n",
153+
"---------------------------------------------------------------------------\n",
154+
"ZeroDivisionError Traceback (most recent call last)\n",
155+
"&lt;ipython-input-10-bbe761e74a70&gt; in &lt;module&gt;\n",
156+
"----> 1 100/0\n",
157+
"\n",
158+
"ZeroDivisionError: division by zero\n",
159+
"</code>\n",
160+
"</div>"
161+
]
162+
},
163+
{
164+
"cell_type": "markdown",
165+
"metadata": {
166+
"colab_type": "text",
167+
"id": "WICNDncaP8k_"
168+
},
169+
"source": [
170+
"***\n",
171+
"\n",
172+
"## On your own\n",
173+
"\n",
174+
"Close the tutorial section with a horizontal rule. You're free to take any direction now, but here are three suggested sections.\n",
175+
"\n",
176+
"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",
177+
"\n",
178+
"## In practice...\n",
179+
"\n",
180+
"- The fine print that you avoided can go in this section.\n",
181+
"\n",
182+
"\n",
183+
"\n",
184+
"- Don't just say it's usually done another way; explain why. \n",
185+
" \n",
186+
"\n",
187+
"## Further reading\n",
188+
"\n",
189+
"- 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",
190+
"- The Google guide is long; there's also [a summary](https://developers.google.com/style/highlights?hl=pt-br).\n",
191+
"- NumPy's website includes a [documentation how-to](https://numpy.org/devdocs/dev/howto-docs.html)."
192+
]
193+
}
194+
],
195+
"metadata": {
196+
"colab": {
197+
"include_colab_link": true,
198+
"name": "tutorial-svd.ipynb",
199+
"provenance": []
200+
},
201+
"kernelspec": {
202+
"display_name": "Python 3",
203+
"language": "python",
204+
"name": "python3"
205+
},
206+
"language_info": {
207+
"codemirror_mode": {
208+
"name": "ipython",
209+
"version": 3
210+
},
211+
"file_extension": ".py",
212+
"mimetype": "text/x-python",
213+
"name": "python",
214+
"nbconvert_exporter": "python",
215+
"pygments_lexer": "ipython3",
216+
"version": "3.8.3"
217+
}
218+
},
219+
"nbformat": 4,
220+
"nbformat_minor": 4
221+
}

0 commit comments

Comments
 (0)