学习编写 NumPy 教程

学习编写 NumPy 教程#

The Diátaxis framework for documentation dividing tutorials, how-to guides, explanation, and reference

图片来源：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 所解释的

不要解释任何学习者为了完成教程不需要知道的内容。

因为教程步骤被设计为清晰易懂，它们可能达不到生产级水平。是的，你应该分享这一点，但不是在教程中，教程本身应该直接且确定。In practice 部分是放置细节、例外、替代方案以及类似注意事项的地方。

使用图表和插图#

图形是双赢的；它们能强化你的观点并使页面更具吸引力。就像英语技能一样，美术技能（或图形工具技能）不是必需的。即使你只扫描了一幅手绘插图，也会有人能将其润色。

标题下方的插图，即使它只是装饰性的，也能使你的页面独具特色。

尽可能使用真实数据集#

读者更容易被真实的用例所吸引。请确保你拥有数据的使用权。

教程和操作指南 — 相似但不同#

教程读者是外来者，他们想了解这个地方。选择任何一个目的地，并沿途解释景点。

与知道自己需要什么的操作指南读者不同，教程读者不知道他们不知道什么。所以，虽然教程需要像你将做什么和你将学到什么这样的标题，但这些标题绝不会出现在操作指南中。

利用 Google 文档风格指南#

NumPy 文档遵循 Google 开发者文档风格指南。除了提供常见问题的答案（是“crossreference”还是“cross-reference”？），该指南还充满了可以增强你的文档编写的建议。

Notebook 必须完全可执行#

Run all cells 应该执行文件中所有单元格直到文件底部。如果你正在演示一个错误的表达式并想显示回溯，请注释掉该表达式并将回溯放在文本单元格中。

（请注意，对于包含 <text inside angle brackets> 的回溯，三个反引号是不够的，尖括号必须被 &lt; 和 &gt; 替换，如下面文本单元格 markdown 所示。）

# 100/0
--------------------------------------------------------------------------- ZeroDivisionError Traceback (most recent call last) <ipython-input-10-bbe761e74a70> in <module> ----> 1 100/0

ZeroDivisionError: division by zero

独立练习#

用一条水平线结束教程部分。你现在可以自由选择任何方向，但这里有三个建议的部分。

在可选的 On your own 部分，你可以为读者提供一个练习新技能的作业。如果它是一个有答案的问题，请提供答案——也许以脚注形式，以免剧透。

实践中…#

  • 你所避免的细节或注意事项可以放在这一部分。

  • 不要只说通常有其他做法；请解释原因。

延伸阅读#

目录