学习编写 NumPy 教程#
图片版权：Daniele Procida 的 Diátaxis 框架，根据 CC-BY-SA 4.0 许可。
你将做什么#
在模板的指导下，你将编写一个 NumPy 教程。
你将学到什么#
你将能够创建一个遵循标准格式并反映良好教学实践的教程。
你将学习 NumPy 教程开头三个标准标题——**你将做什么**、**你将学到什么**和**你将需要什么**——以及底部一些可选标题——**独立练习**、**实践**、**进一步阅读**。
你将了解是什么让**你将学到什么**与**你将做什么**不同。
你将能够区分**教程**和**操作指南**。
你将学习在**你将学到什么**部分中不应该放入什么内容。
你将需要什么#
这个模板。
你目标读者的画像。
就像学校列出高级课程的先决条件一样，你可以假设读者知道某些事情（你必须列出，如下一个项目符号所示）。过度解释会拖慢教程的进度并掩盖要点。
但也要设身处地为读者着想，并考虑沿途需要解释的内容。
“你将需要什么”是一个列表，列出
用户开始之前必须在其机器上存在的包。不要包含
numpy。你假设读者在上面的项目符号中知道的内容。不要说
Python；熟悉 Python 迭代器是可以的。
随意性和热情。想象一下你的读者不是坐在观众席上，而是坐在你旁边。
愿意为**你将需要什么**项目符号编写不完整的句子。它们不会以“你将需要”开头。
**不需要**的是英语母语能力。其他人可以帮忙。
在水平线之后，开始你自己的标题#
你的教程步骤从这里开始，使用你选择的标题。在教程结束时，你将放置另一个水平线并返回到标准标题。
标题要有动词#
一般来说，标题中要包含一个动词；因此是**学习编写 NumPy 教程**而不是“NumPy 教程规则”。考虑在标题中也使用动词。
标题使用小写字母#
将第一个单词大写，之后只大写通常大写的单词（所以不是“标题是大写的”）。
在“你将学到什么”中要说些什么#
避免抽象。“关于”是一个提示：与其写“你将学习 NumPy I/O”，不如写“你将学习如何将逗号分隔的文本文件读入 NumPy 数组”。
为什么“你将做什么”和“你将学到什么”不同？#
**你将做什么**通常是一个句子，列出最终产品：“你将烤一个蛋糕。”这使得终点很清楚。**你将学到什么**列出了回报，并且可能有许多回报：“你将学习如何遵循食谱。你将练习测量配料。你将学习如何判断蛋糕何时可以出炉。”
避免旁注#
正如专家文档编写者 Daniele Procida 所解释的
不要解释学习者为了完成教程不需要了解的任何内容。
由于教程步骤的选择是为了清晰易懂，它们可能达不到生产级标准。是的，你应该分享这一点，但不应在教程中分享，教程应该简单明了且可靠。实践部分是用于细节、例外、替代方案和类似细节的地方。
使用图表和插图#
图表是一举两得；它们可以增强你的观点，并使页面更具吸引力。像英语技能一样，艺术技能（或图形工具集技能）不是必需的。即使你只扫描手绘插图，也有人可以对其进行润色。
标题下方的插图，即使只是装饰性的，也会使你的页面与众不同。
尽可能使用真实数据集#
读者更有可能参与到真实的用例中。确保你拥有数据的权利。
教程和操作指南——相似但不同#
教程读者是外地人，他们想了解这个地方。选择任何一个目的地，并解释沿途的景点。
与知道自己需要什么的操作指南读者不同，教程读者不知道自己不知道什么。因此，虽然教程需要像**你将做什么**和**你将学到什么**这样的标题，但这些标题永远不会出现在操作指南中。
使用 Google 文档样式指南#
NumPy 文档遵循 Google 开发者文档样式指南。除了提供对重复出现的问题的答案（“交叉引用”还是“交叉引用”？）之外，该指南还提供了许多建议，这些建议将增强你的文档编写能力。
笔记本必须完全可执行#
运行所有单元格应该执行文件底部的所有单元格。如果你正在演示一个错误的表达式并想要显示回溯，请注释该表达式并将回溯放在文本单元格中。
（请注意，对于包含 <角度括号内的文本> 的回溯，三个反引号是不够的，角度括号必须替换为 < 和 >，如下面的文本单元格 markdown 所示。）
# 100/0
--------------------------------------------------------------------------- ZeroDivisionError Traceback (most recent call last) <ipython-input-10-bbe761e74a70> in <module> ----> 1 100/0ZeroDivisionError: division by zero
独立练习#
用水平线关闭教程部分。你现在可以自由地选择任何方向，但这里有三个建议的部分。
在一个可选的 独立练习 部分中，你可以为读者提供一项作业来练习他们的新技能。如果这是一个有答案的问题，请提供答案——也许放在脚注中，以避免剧透。
实践……#
你避免的细节可以放在这个部分。
不要只是说它通常以另一种方式完成；解释原因。