学习编写一个 NumPy 教程#
Image credit: Daniele Procida's Diátaxis framework, licensed under CC-BY-SA 4.0.
你将做什么#
在模板的指导下，你将编写一个 NumPy 教程。
你将学到什么#
你将能够编写一个遵循标准格式并反映良好教学实践的教程。
你将学习到三个标准的标题，这些标题开启了一个NumPy教程 – 你要做什么, 你要学习什么, 和 你需要什么 – 以及一些可选的底部标题 – 自己动手, 实践, 进一步阅读.
你会知道 What you’ll learn 与 What you’ll do 的不同之处。
你将能够区分一个 教程 和一个 操作指南。
你将学习到不要在 你将学习到的内容 部分中放入什么。
你需要什么#
这个模板。
你目标读者的肖像。
正如学校列出高级课程的先决条件一样，你可以假设读者知道一些事情（你必须列出这些事情，如下一个项目符号所指出的）。过度解释会使教程变得冗长，并掩盖主要内容。
但也要设身处地为读者着想，并考虑一路上要解释什么。
“你需要的东西” 是一个列表：
在用户开始之前，必须存在于用户机器上的包。不要包括
numpy。你在上面列表项中假设读者知道的内容。不要说
Python；熟悉 Python 迭代器是可以的。
非正式和热情。想象你的读者不在观众中，而是在你旁边。
愿意为 所需内容 项目符号编写不完整的句子。它们不以“你需要”开头。
不 需要的是母语为英语的技能。其他人也可以帮忙。
在水平规则之后，开始你自己的标题#
您的教程步骤从这里开始，使用您选择的标题。在教程结束时，您将放置另一个水平规则并返回到标准标题。
标题有动词#
通常，在标题中包含一个动词；因此 学习编写一个 NumPy 教程 而不是 “NumPy 教程的规则。” 考虑在标题中也使用动词。
标题是小写的#
首词大写，之后只有通常大写的词（所以不是“Titles Are Lowercase”）。
在“你将学到什么”中该说什么#
避免抽象。“关于”是一个提示：与其写“你将学习关于NumPy I/O”，不如写“你将学习如何将逗号分隔的文本文件读取到NumPy数组中。”
为什么“你要做什么”和“你要学什么”不同？#
你要做什么 通常是一句话列出一个最终产品：“你要烤一个蛋糕。” 这使得目标明确。你要学什么 列出收益，可能有很多：“你要学会按照食谱操作。你要练习测量食材。你要学会如何判断蛋糕是否烤好了。”
避免离题#
正如专家文档撰写者 Daniele Procida 所解释的：
不要解释学习者在完成教程时不需要知道的内容。
因为教程步骤选择清晰和简单，它们可能达不到生产级别。是的，你应该分享这个，但不是在教程期间，教程应该是直接和确定的。实际操作部分是详细信息、例外、替代方案和类似细则的地方。
使用图表和插图#
图像是双赢的；它们增强了你的观点并使页面具有吸引力。就像英语技能一样，艺术技能（或图形工具技能）不是必需的。即使你只扫描了一个手绘图，也有人可以润色它。
标题下方的一幅插图，即使它只是装饰性的，也能使您的页面与众不同。
在可能的情况下使用真实数据集#
读者更有可能被一个真实的用例所吸引。确保您有权使用这些数据。
教程和操作指南 – 相似但不同#
教程读者是那些想要感受这个地方的外地人。选择任何一个目的地并解释沿途的景点。
与知道他们需要什么的操作指南读者不同，教程读者不知道他们不知道什么。因此，虽然教程需要像 你要做什么 和 你要学什么 这样的标题，但这些标题永远不会出现在操作指南中。
使用 Google 文档风格指南#
NumPy 文档遵循 Google 开发者文档风格指南。除了提供对常见问题的答案（“交叉引用”还是“交叉-引用”？），该指南还充满了能增强你文档写作的建议。
笔记本必须完全可执行#
运行所有单元格 应该执行文件底部的所有单元格。如果你在演示一个错误的表达式并想展示回溯，请注释该表达式并将回溯放入一个文本单元格中。
（注意，对于包含 <text inside angle brackets> 的回溯，三重反引号是不够的，尖括号必须替换为 < 和 >，如下面文本单元格的 markdown 所示。）
# 100/0
---------------------------------------------------------------------------
ZeroDivisionError Traceback (most recent call last)
<ipython-input-10-bbe761e74a70> in <module>
----> 1 100/0
ZeroDivisionError: 除以零
在你自己#
用一条水平线结束教程部分。你现在可以自由选择任何方向，但这里有三个建议的部分。
在可选的 On your own 部分，你可以提供一个任务让读者练习他们的新技能。如果这是一个有答案的问题，请提供答案——可能以脚注的形式，以避免成为剧透。
在实践中…#
你避免的那些细则可以放在这一部分。
不要只是说通常有另一种做法；解释为什么。