学习编写 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 开发者文档样式指南。除了提供对重复出现的问题的答案（“交叉引用”还是“交叉引用”？）之外，该指南还充满了建议，可以增强您的文档写作能力。
笔记本必须完全可执行#
运行所有单元格 应该执行所有单元格到文件的底部。如果您正在演示一个错误的表达式并想要显示回溯，请注释掉该表达式并将回溯放在一个文本单元格中。
（请注意，对于包含 <角度括号内的文本> 的回溯，三重反引号是不够的，角度括号必须用 < 和 > 替换，如下面的文本单元格标记所示。）
# 100/0
--------------------------------------------------------------------------- ZeroDivisionError Traceback (most recent call last) <ipython-input-10-bbe761e74a70> in <module> ----> 1 100/0ZeroDivisionError: division by zero
自己动手#
使用水平线关闭教程部分。现在您可以自由地采取任何方向，但这里有三个建议的部分。
在可选的 自己动手 部分，您可以为读者提供一个作业，让他们练习新的技能。如果是带答案的问题，请提供答案 - 也许放在脚注中，以免成为剧透。
实际上…#
您所避免的细则可以放在本节中。
不要仅仅说它通常以另一种方式完成；解释原因。