图片来源：Daniele Procida 的 Diátaxis 框架，根据 CC-BY-SA 4.0 许可。
您将做什么¶
在模板的指导下，您将编写一份 NumPy 教程。
您将学到什么¶
您将能够制作出一份遵循标准格式并体现良好教学实践的教程。
您将了解打开 NumPy 教程的三个标准标题——您将做什么， 您将学到什么， 和 您将需要什么——以及底部的一些可选标题——自己动手， 实践中， 扩展阅读。
您将知道 您将学到什么 与 您将做什么 的区别。
您将能够区分 教程 和 操作指南。
您将学到 您将学到什么 部分不应该包含什么。
您将需要什么¶
本模板。
您的目标读者的画像。
正如学校会列出更高阶课程的先修条件一样，您可以假定读者已经知道一些东西（您必须列出它们，如下一个要点所述）。过度解释会拖慢教程的进度并模糊主要观点。
但也要站在读者的角度，考虑沿途需要解释的内容。
“您将需要什么”是关于
用户机器上必须存在的软件包列表。不要包含
numpy。您在上面要点中假定读者知道的内容。不要说
Python；熟悉 Python 迭代器就可以了。
非正式和热情。想象您的读者不在观众席中，而是在您身边。
愿意为 您将需要什么 的要点写不完整的句子。它们不以“您需要”开头。
不 要求具备流利的英语技能。其他人可以帮忙。
在一条水平线之后，开始您自己的标题¶
您的教程步骤从这里开始，使用您选择的标题。在教程结束时，您将放置另一条水平线并返回到标准标题。
标题包含动词¶
一般来说，在标题中包含动词；因此，学习编写 NumPy 教程 而不是“NumPy 教程规则”。考虑在标题中也包含动词。
标题为小写¶
首字母大写第一个单词，之后只大写通常需要大写的单词（所以不是“Titles Are Lowercase”）。
“您将学到什么”部分该说什么¶
避免抽象。“关于”是一个提示：与其写“您将了解 NumPy I/O”，不如写“您将学会如何将逗号分隔的文本文件读入 NumPy 数组。”
为什么“您将做什么”和“您将学到什么”不同？¶
您将做什么 通常是一句话，列出一个最终产品：“您将烤一个蛋糕。”这使得终点清晰。您将学到什么 列出了好处，可能有许多：“您将学会遵循食谱。您将练习测量配料。您将学会如何判断蛋糕何时可以出炉。”
避免题外话¶
正如专家文档编写者 Daniele Procida 所解释的
不要解释学习者为了完成教程而不需要知道的任何内容。
由于教程的步骤选择清晰易懂，它们可能达不到生产级别。是的，您应该分享这一点，但不是在教程中，教程应该简单明了且有信心。实践中 部分是关于细节、例外、替代方案和类似细则的地方。
使用图表和插图¶
图表是双赢；它们放大了您的观点，并使页面更具吸引力。与英语技能一样，艺术技能（或图形工具集技能）不是必需的。即使您只画一个粗略的手绘插图，也可以有人对其进行完善。
标题下方的插图，即使只是装饰性的，也能使您的页面独具特色。
尽可能使用真实数据集¶
读者更有可能被真实的用例所吸引。请确保您拥有数据的使用权。
教程与操作指南——相似但不同¶
教程读者是想对这个地方有所了解的游客。选择任何一个目的地，并沿途解释景点。
与操作指南的读者不同，操作指南读者知道他们需要什么，而教程读者不知道他们不知道什么。因此，虽然教程需要您将做什么和您将学到什么这样的标题，但这些标题在操作指南中永远不会出现。
利用 Google 文档风格指南¶
NumPy 文档遵循 Google 开发者文档风格指南。该指南不仅提供了常见问题的答案（“crossreference”还是“cross-reference”？），还充满了可以加强您文档写作的建议。
笔记本必须完全可执行¶
运行所有单元格 应该执行到文件底部的所有单元格。如果您要演示一个错误的表达式并想显示回溯，请注释掉该表达式，并将回溯放在一个文本单元格中。
（请注意，三连反引号不足以处理包含 <尖括号内的文本> 的回溯，必须将尖括号替换为 < 和 >，如下面的文本单元格 markdown 所示。）
# 100/0--------------------------------------------------------------------------- ZeroDivisionError Traceback (most recent call last) <ipython-input-10-bbe761e74a70> in <module> ----> 1 100/0 ZeroDivisionError: division by zero自己动手¶
用一条水平线结束教程部分。现在您可以自由地选择任何方向，但这里有三个建议的章节。
在可选的 自己动手 部分，您可以为读者提供一个练习他们新技能的作业。如果这是一个带有答案的问题，请提供答案——也许在脚注中，以免剧透。
实践中...¶
您避免的细则可以放在本节中。
不要只说通常会用另一种方式来做；要解释原因。
进一步阅读¶
理想情况下，扩展阅读 在提供裸链接而不是描述引用：The Documentation System 是本教程的灵感来源，并描述了其他三种文档类型。
Google 指南很长；还有一个摘要。
NumPy 网站包含一个文档操作指南。