学习编写 NumPy 教程#
图片来源：Daniele Procida 的Diátaxis 框架，已获得CC-BY-SA 4.0许可。
你会做什么#
在模板的指导下，您将编写 NumPy 教程。
你将学到什么#
您将能够编写遵循标准格式并反映良好教学实践的教程。
您将学习打开 NumPy 教程的三个标准标题 –您将做什么、 您将学到什么以及您将需要什么– 以及底部的一些可选标题 –自行、 实践、 进一步阅读。
你会知道是什么让你将学到的东西与你将要做的事情不同。
您将能够区分教程和操作方法。
您将了解哪些内容不应放入“您将学到的内容”部分。
你需要什么#
这个模板。
您的目标读者的肖像。
正如学校列出了高级课程的先决条件一样，您可以假设读者知道一些事情（您必须列出这些事情，如下一个项目符号所示）。过度解释会使教程陷入困境并模糊了要点。
但也要设身处地为读者着想，考虑一路上要解释什么。
“您需要什么”是以下内容的列表：
开始之前用户计算机上必须存在的软件包。不包括
numpy.您假设读者在上面的项目符号中知道什么。别说
Python； 很好。familiarity with Python iterators
非正式和热情。想象一下你的读者不是在观众席上，而是在你旁边。
愿意为“您需要什么”项目符号写出不完整的句子。它们不会以“你需要”这样的词开头。
不需要母语英语技能。其他人可以提供帮助。
在水平线之后，开始您自己的标题#
您的教程步骤从这里开始，使用您选择的标题。在教程结束时，您将放置另一条水平线并返回到标准标题。
标题有动词#
一般来说，标题中包含一个动词；因此学习编写 NumPy 教程而不是“NumPy 教程规则”。也可以考虑将动词放在标题中。
标题为小写#
将第一个单词大写，之后仅使用通常大写的单词（因此不是“Titles Are Lowercase”）。
“你将学到什么”中该说什么#
避免抽象。 “关于”是一个提示：不要写“您将了解 NumPy I/O”，而应写“您将学习如何将逗号分隔的文本文件读入 NumPy 数组”。
为什么“你将做什么”和“你将学到什么”不同？#
您要做的通常是用一句话列出最终产品：“您将烤一个蛋糕。”这使得终点变得清晰。你将学到的内容列出了回报，而且可能有很多：“你将学会遵循食谱。您将练习测量成分。您将学习如何判断蛋糕何时可以从烤箱中取出。”
避免旁白#
不要解释学习者完成教程不需要了解的任何内容。
由于教程步骤被选择为清晰易懂，因此它们可能达不到生产级别。是的，您应该分享这一点，但不要在教程期间分享，这应该是简单而有保证的。该部分是详细信息、例外情况、替代方案和类似精美印刷的地方。In practice
使用图表和插图#
数字是双赢；它们会放大你的观点并使页面更具吸引力。与英语技能一样，艺术技能（或图形工具集技能）也不是必需的。即使你只扫描手绘插图，也有人可以对其进行润色。
标题下方的插图，即使只是装饰性的，也能让您的页面与众不同。
尽可能使用真实数据集#
读者更有可能被真实的用例所吸引。确保您拥有数据的权利。
教程和操作方法 – 相似但不同#
教程的读者是外地人，想要感受一下这个地方。选择任意一个目的地并解释沿途的景点。
与知道自己需要什么的指南读者不同，教程读者不知道他们不知道什么。因此，虽然教程需要诸如“您将做什么”和“您将学到什么”之类的标题，但这些标题永远不会出现在操作方法中。
利用 Google 文档风格指南#
NumPy 文档遵循Google 开发人员文档风格指南。除了提供重复出现的问题的答案（“交叉引用”或“交叉引用”？）之外，该指南还提供了有助于加强您的文档写作的建议。
笔记本必须完全可执行#
Run all cells应该执行文件底部的所有单元格。如果您正在演示错误的表达式并希望显示回溯，请注释该表达式并将回溯放入文本单元格中。
（请注意，对于包含 的回溯来说，三重反引号是不够的，尖括号必须替换为和 ，如下面的文本单元格标记所示。）<text inside angle brackets><>
# 100/0
---------------------------------------------------------------------------
ZeroDivisionError Traceback (most recent call last)
<ipython-input-10-bbe761e74a70> in <module>
----> 1 100/0
ZeroDivisionError: division by zero
靠你自己#
用水平尺关闭教程部分。您现在可以自由选择任何方向，但这里有三个建议的部分。
在可选部分中，您可以为读者提供作业以锻炼他们的新技能。如果这是一个有答案的问题，请提供它——也许在脚注中，以免剧透。On your own
在实践中… ＃
您避免使用的细则可以放在本节中。
不要只是说它通常是用另一种方式完成的；解释为什么。