Steve LoshBlog - Projects - Photography - Links - Feed

Teach, Don't Tell

发表于 2013年9月3日。

这篇文章是关于编写技术文档的。更具体地说：是关于为编程语言和库编写文档。

我喜欢阅读优秀的文档。当我有一个问题，而文档几乎就像作者神奇地预见到了我的问题一样，解释了答案时，我内心会感到温暖和模糊。 我感到与作者建立了一种连接，这让我微笑。

我也喜欢编写文档。能够重新连接某人大脑中的神经元，让他们理解以前不理解的东西，这是非常令人满意的。看到（或听到）当一堆概念突然结合在一起并变得有意义时的“咔哒”声，总是能让我开心一整天。

这篇文章将讲述我认为好的文档是什么，以及我认为你应该如何编写它。我并不完美，所以你应该对一切都持保留态度，但我希望即使你不同意我的所有观点，你也会觉得它有用且发人深省。

我想感谢 Craig Zheng 和 Honza Pokorny 帮我校对。

  1. 前置阅读
  2. 我们为什么要编写文档？
  3. 教学
  4. 七幕剧
  5. 第一幕：“阅读源码”
  6. 行业工具
  7. 第二幕：“阅读测试”
  8. 如何教学
  9. 第三幕：“文学编程”
  10. 好的文档的剖析
  11. 初次接触
  12. 第四幕：“阅读文档字符串”
  13. 黑色三角
  14. 第五幕：“阅读 API 文档”
  15. 一团乱麻
  16. 第六幕：“阅读 Wiki”
  17. 参考
  18. 第七幕：“新的希望”

前置阅读

在你阅读这篇文章之前，我认为你应该先阅读另外两件事。

第一件事是 Jacob Kaplan-Moss 的 Writing Great Documentation 系列。他当然比我更有资格写关于这些东西的文章，所以如果你还没有看过，你应该看看。我在这里说的很多内容都将与他所谈论的想法相一致并在此基础上构建。

你应该阅读的另一件事是 George Gopen 和 Judith Swan 的 The Science of Scientific Writing。不要因为它是为在期刊上发表论文的科学家而写的而退缩。这篇文章中的所有内容同样适用于编写技术文档的程序员。阅读整个内容。这是值得的。

我们为什么要编写文档？

让我们开始吧。首先要确定的是，我们首先_为什么_要记录一种编程语言或库。你可能想要完成很多事情，但我将把它们归结为一个单一的陈述：

技术文档的目的是让一个从未见过你的项目的人，教他们成为该项目的专家用户，并在他们成为专家后支持他们。

乍一看，这可能看起来并不太有争议或有趣。但是其中有一个词使_一切_都不同，并且它构成了我对文档的整个看法。

教学

如果你想把一个从未弹过吉他的人变成一个吉他大师，你该怎么做？

你_教_他们。

如果你想把一个高中生变成一个计算机科学家，你该怎么做？

你_教_他们。

如果你想把一个以前从未见过你的库的程序员变成它的专家用户，你该怎么做？

你_教_他们！

吉他课程通常由老师面对面地一对一教授。计算机科学通常由教授在教室里教授。编程库的使用通常由文档教授。

如果文档的目标是将新手变成专家，那么_文档必须教_。你应该把你的文档看作是一节课（或一系列课程），因为_这就是它_。

在编写技术文档时，你（通常）没有与学习者进行一对一对话的优势。这使它有点困难，但只要你小心，就不是不可能的。你的文档需要同时扮演面授课程_和_教科书的角色。

这篇文章的其余部分将几乎完全是关于如何将“文档是教学”的心态应用于编写编程文档的。

七幕剧

我将用一些关于_糟糕_文档的发泄来打断这篇文章的内容。如果你想跳过这些小小的咆哮，请继续。

我们剧中的每一幕都有两个角色：一个青少年和一个家长。这个青少年刚满十六岁，想学会开车，这样他们就可以和朋友一起出去玩，而不依赖父母开车送他们到处走。

每一幕都将展示一个特别_糟糕_的文档形式的漫画。我希望这些小小的比喻能够帮助说明为什么某些形式的文档是无效的托词，以及为什么你应该编写_真正的_文档来代替。

第一幕：“阅读源码”

我们的剧从儿子和父亲坐在早餐桌旁开始。儿子在上学前狼吞虎咽地吃着一些谷物，而父亲在上 iPad 上看书，然后去上班。

儿子说：“嘿，爸爸，你说过今天放学后你要教我开车。我们还要做吗？”

父亲没有从 iPad 上抬起头，回答说：“当然，儿子。汽车在车库里，我在工作台上放了一套扳手。把汽车拆开，看看每一块，然后把它装回去。一旦你完成了，我就会带你去车管所参加你的驾驶考试。”

儿子默默地继续吃着他的谷物。

如果你使用许多开源库，你无疑会遇到一些 README 说“阅读源码”的。每次我看到一个，我内心都会死一点点。

源码_不是_文档。你能通过简单地专心听一首乐曲来学会弹吉他吗？你能通过参观很多博物馆成为一名画家吗？当然不能！

让我说清楚：我不是想说阅读源码不是一件有价值的事情。它是！

一旦你懂得如何绘画，那么看看其他艺术家的画作就非常有用。一旦你知道如何驾驶，那么了解汽车的刹车是如何构造的可以挽救你的生命。

一旦你的库的用户知道如何使用它，阅读它的源码绝对值得他们花时间。但是，如果没有额外的指导，你无法仅仅通过查看成品来理解其中的观点和想法。那是文档的工作。

行业工具

编写好的文档不需要太多的工具。

例如：你不需要同义词词典。不要试图通过替换同义词来避免使用相同的词。像你会在现实生活中与另一个人交谈一样与你的用户交谈！

如果你连续使用同一个词十次，你的读者可能甚至不会注意到。但我保证，如果你没有理由地扔进奇怪的、不常见的词语，他们会注意到的。

在继续之前，我_将_推荐两个工具。第一个实际上不是一个工具，而是一种技能。

要编写出色的文档，你需要能够打字。

当你编写文档时，你不可避免地会将自己写进一个死胡同，并意识到你需要采取一个新的方向。如果你打字不快，你可能会犹豫是否要扔掉那些实际上不起作用的文字。你需要学会打字，这样你才不会因为扔掉一大块不合适的文字而感到难过。

Steve Yegge 的文章 Programming's Dirty Little Secret 是一个关于这个话题的精彩咆哮。

你也应该给自己买一个漂亮的键盘。一个好的键盘不会让你成为一个好的作家（就像一把好的吉他不会让你成为一个好的吉他手一样），但是它_会_让你因为仅仅是使用一件精心设计的设备的纯粹乐趣而想要写更多东西。

在我得到一把比我的旧吉他好得多的新吉他后，我开始练习吉他更多了。如果你花一百美元，买一个漂亮的键盘，最终想要写更多东西，那就是值得的！

值得庆幸的是，一个好的键盘只需要花费 100 到 300 美元，而不是像一件好的乐器那样花费数千美元。

第二幕：“阅读测试”

下一个场景从一位母亲从高中接女儿开始。

“嗨，妈妈”，她说，“你今天还要教我开车吗？”

“是的！”她回答说。“我们走吧。”

开了十分钟的车后，他们到达了雪佛兰工厂。

女孩困惑地环顾四周。她问：“我们在这里做什么？”

母亲笑着说：“你很幸运，亲爱的，我的朋友吉姆在这里的雪佛兰工厂工作，他会让你观看一些新款 Malibu 的碰撞测试！一旦你看到几辆汽车互相撞击，我就会带你去车管所参加你的驾驶考试。”

另一种常见的“文档”形式是 README 指示用户“阅读测试”。

测试不是文档。

再说一遍，让我们说清楚：一旦你已经知道如何使用一个库，阅读测试就_非常_有用。但是你需要文档来让你首先成为一个专家用户！

你不能通过观看碰撞测试来学会开车。但是，了解你的汽车在碰撞期间的行为可以挽救你的生命——一旦你知道如何驾驶。

我看到的一个常见论点是这样的：

“测试使用了该库，所以它们是展示如何使用它的一个很好的例子！”

这在某种非常肤浅的意义上是正确的，但完全没有抓住重点。

大多数测试可能会处理边缘情况。边缘情况是普通用户不会经常遇到的事情（否则它们就不会是边缘情况！）。

如果你很幸运，你可能会得到一个验证该库在正常输入集上是否正常工作的测试。但是“正常输入集”是用户将在大多数时间里使用的东西！

测试根本不是用户在日常生活中会遇到的情况的一个很好的指南。它们无法将新手变成专家。

如何教学

如果你接受我的想法，即文档的目的是_教_用户，那么下一个问题显然是：“我如何教我的用户？”

我很幸运有机会以半正式的方式教授舞蹈大约 6 或 7 年，并且长期以来以非正式的方式教授许多其他各种事情。真正学会如何教学的唯一方法是_去做_。

没有什么可以替代与某人面对面坐下来并教他们一些东西。如果你想编写更好的文档，你需要练习教学。

我不是在谈论写教案或任何如此正式的东西。你有什么爱好（不是编程）吗？如果有，花几个小时在一个周末教一个朋友关于它的知识。你将获得一些教学练习，他们将学习一些新东西。

（如果你没有任何非编程爱好，也许你应该找一些。）

如果你喜欢摄影，教某人曝光和构图的基础知识。如果你跳舞，教他们一些基本的舞步。如果你演奏乐器，教他们如何演奏一首简单的歌曲。如果你喜欢露营，教他们所有装备的用途。你明白了吗。

不要太过分。你不需要给某人一个学位，你只需要练习一下教学。你需要练习用你的话重新连接某人的神经元的艺术。

一旦你开始教一些东西（即使是很简单的东西），你可能会意识到，虽然你知道如何自己做，但教别人要困难得多。

当你与某人面对面工作时，这很明显。当你告诉他们如何在吉他上弹奏 C 大调和弦时，他们只会发出一种令人窒息的吱吱声，很明显你需要放慢速度并谈谈如何正确地按下琴弦。

作为程序员，我们几乎_从不_收到关于我们的文档的这种反馈。我们没有看到电线另一端的人完全困惑和摸索，因为他们遗漏了一些我们认为显而易见的东西（但事实并非如此）。亲自教某人可以帮助你学会预测这一点，这将在你编写文档时（为你的用户）得到回报。

说了这么多，我还想稍微谈谈实际的教学过程。

到目前为止，我见过的关于如何教学的最佳描述来自 How to Solve It 这本书。每个想教学的人都应该阅读这本书。真正让我印象深刻的那段话就在第一章的第一页：

[教师帮助学生]的最佳[方式]是自然地帮助学生。教师应该把自己放在学生的位置上，他应该看到学生的情况，他应该尝试理解学生脑海中发生了什么，并提出一个问题或指出一个_学生自己可能想到_的步骤。

这，就在这里，是教学的核心。这就是它。这就是你如何做到的。

人们不会通过简单地吸收大量非结构化信息来学习。你不能向某人阅读一本西班牙语词典来教他们西班牙语。

当你想要教某人时，你需要把自己放在他们的位置上，并与他们一起走这条路。握住他们的手，引导他们绕过危险的障碍，并在他们跌倒时抓住他们。_不要_带着他们。_当然不要_只是开着你的车把他们送到目的地！

这个过程需要像这样进行：

  1. 弄清楚他们已经知道什么。
  2. 弄清楚你希望他们在完成后知道什么。
  3. 弄清楚一个单一的想法或概念，这将使状态 1 更接近状态 2。
  4. 朝着那个想法的方向轻轻地推动学生。
  5. 重复，直到状态 1 变为状态 2。

我经常看到文档非常仔细地考虑了步骤 2，然后只是把它作为上帝的宣告呈现给读者。这不是教学。那是告诉。人们不会通过被_告知_来学习，他们通过被_教导_来学习。

第三幕：“文学编程”

第三幕从女儿在她十六岁生日前一天与她的母亲交谈开始。

“嘿，妈妈，”她说，“我不知道你是否给我买了礼物，但如果没有，我_真的_想要的生日礼物是驾驶课程。”

母亲笑着说：“别担心，一切都安排好了。只要等到明天。”

第二天在她的生日聚会上，她拆开了她妈妈送的礼物。里面是电视节目《How It's Made》的 DVD。她疑惑地看着她的母亲。

“那个 DVD 有一集是关于制造你的汽车的工厂的！一旦你看完了整个节目，我就会带你去参加你的驾驶考试。”

我最近注意到的一种可怕的趋势是使用像 Docco、Rocco 等“文学编程”工具，并告诉用户阅读结果以获取文档。

编程语言和库是工具。知道工具是如何制造的并不意味着你知道如何使用它。当你上吉他课时，你不会拜访一个制琴师来观看她用白蜡木塑造一把 Telecaster。

一旦你知道如何驾驶，知道你的汽车是如何建造的可以帮助你。

一旦你知道如何弹奏，知道你的吉他是如何建造的可以帮助你。

贯穿这些幕/咆哮的一个共同主题是，所有我正在挑剔的这些东西（源码、测试、文学编程等等）都是好东西，一旦你有了实际的文档来教用户，它们就会带来真正的好处。

但是在这种情况发生之前，它们实际上是_坏的_，因为它们让你假装你已经编写了文档，并且你的工作已经完成了（JKM 在他的系列中提到了这一点）。在您教给您的用户足够的知识以成为专家之前，您的工作还没有完成。_然后_他们可以利用所有这些额外的东西。

好的文档的剖析

这篇文章的其余部分将讲述组成好的文档的各个组成部分。我的观点与 JKM 的非常相似，所以如果你还没有阅读我在第一节中提到的系列文章，你应该这样做。

在我看来，我将好的文档大致分为四个部分：

  1. 初次接触
  2. 黑色三角
  3. 一团乱麻
  4. 参考

每个部分不一定需要四个单独的文档。事实上，前两个通常可以合并到一个文件中，而最后两个可能应该分成多个部分。但我认为每个组件都是好的文档中一个独特而重要的部分。

让我们看看每个组件。

初次接触

当你将一种新的编程语言或库发布到野外时，你的“用户”的初始状态将是空白。当他们遇到你的库时，他们需要知道的事情是：

  1. 这是什么东西？
  2. 我为什么要关心这个东西？
  3. 学习这个东西值得吗？

你的“初次接触”文档应该向他们解释这些事情。

你不需要从第一性原理开始解释事情。试着把自己放在用户的角度上。当你教你的青少年开车时，你不需要解释什么是“轮子”。他们可能有一些关于“你在里面移动的带轮子的东西”的经验，比如割草机或高尔夫球车（甚至电子游戏）。

同样：如果你正在创建一个 Web 框架，那么大多数偶然发现你的项目的人可能都知道什么是“HTML”。稍微偏向谨慎一点，多解释一点而不是假设太多是好的，但你可以在这里实用一点。

你的“初次接触”文档应该用简单的语言解释你的东西是做什么的。它应该向某人展示他们为什么要关心它。它会节省他们的时间吗？它会花费更多时间，但会更稳定吗？它只是纯粹的乐趣吗？

为了额外的奖励，你也可以提到为什么有人可能_不想_使用你的项目。几乎没有人会提到使用他们的作品所涉及的权衡，所以看到一个项目这样做会让人感到耳目一新。

最后，用户需要知道在这个星球上花费他们有限的时间来更多地了解你的项目是否值得。你应该明确地列出以下内容：

第四幕：“阅读文档字符串”

第四幕。一位父亲终于兑现了他给女儿驾驶课程的承诺。

“好吧，爸爸，”她说，“我准备好了。我以前从未开过车。我们从哪里开始？”

一位四十多岁的妇女走了进来。“这是谁？”女儿问道。

“这是你的驾驶老师，史密斯女士。”父亲回答说。“她会在你开车去拜访爷爷的两个小时的车程中坐在副驾驶座上。如果你在驾驶过程中对汽车的某个部件有任何疑问，你可以问她，她会告诉你关于该部件的一切。这是钥匙，祝你好运！”

在使用文档字符串的语言中，有一种趋势是编写出色的文档字符串并称其为文档。我相信“文档字符串”一词中的“文档”有助于这一点。

文档字符串不提供任何组织或顺序（除了“它们碰巧在其中实现的命名空间”之外）。用户需要以某种方式知道他们需要的功能的名称，才能看到文档字符串，并且他们无法知道这一点，除非你_教_他们。

再说一次，文档字符串在你_了解项目之后_很棒。但是当你在教一个新手如何使用你的库时，你需要引导他们一路走下去，而不是坐下来回答他们设法正确猜测一个魔术词的问题。

黑色三角

下一个重要的文档是“黑色三角”。它应该是一个相对较短的指南，用于启动和运行你的项目，以便用户可以戳它。

这有几个目的。首先，它让用户验证是的，这个字节集合实际上将在他们的机器上运行并_做一些事情_。这是一个快速的健全性检查，即该项目尚未被比特腐蚀，并且在那个时间点仍然可以使用。更重要的是，它让你的潜在用户在画布上涂上一些色彩。

想象一下，如果你去上第一节吉他课，老师说：“好吧，我们将从学习 150 个不同的和弦开始。然后在大约六个月后，我们可以演奏一些歌曲。”没有吉他老师会这样做。他们教你三个和弦，并给你几首俗气的流行歌曲来演奏。这有助于学生了解作为一个吉他手作为一个整体将会是什么样子，并且它给他们一些东西来帮助保持他们的兴趣。

你的“黑色三角”文档应该是一个简短的指南，引导用户完成检索、安装和戳你的项目或语言的过程。

“短”在这里是一个相对的词。一些项目将需要更多的设置才能运行。如果好处足以证明这种努力是合理的，那么这不一定是一个问题。但尽量保持这个过程尽可能短。_只需在屏幕上显示一些东西_然后继续。

第五幕：“阅读 API 文档”

我们的下一个场景在一年后开始，从上一个场景中的父亲与他的儿子交谈开始。

（可悲的是，那个场景中的女儿在一次车祸中丧生，因为她在进入高速公路之前不知道问史密斯女士关于安全带的问题。当然，史密斯女士戴着她的。）

“好吧，儿子，我知道你因为你姐姐发生的事情而有点害怕开车，但我已经解决了这个问题。”

他递给年轻人一本一英寸厚的书。“一路上问史密斯女士问题显然不起作用，所以我们让她写了一两段关于你汽车的每个部件的描述。去吧，从头到尾阅读整个手册，然后开车去看爷爷。”

API 文档就像汽车的用户手册。当出现问题并且你需要更换轮胎时，它是一个天赐之物。但是如果你正在学习开车，它不会帮助你，因为_人们不会通过阅读不相关的字母列表来学习_。

如果你真的尝试面对面地教某人使用你的项目，你可能会发现自己在一个命名空间中谈论一段时间，然后切换到另一个命名空间来涵盖一些相关的东西，然后再切换回第一个命名空间。学习不是一条通过字母表的直线路径，而是通过别人的大脑进行的曲折漫步。

一团乱麻

这把我带到了下一种类型的文档：“一团乱麻”。到目前为止，用户已经看到了“初次接触”文档和“黑色三角”文档。你已经让他们着迷并准备好学习，但他们仍然是新手。

“一团乱麻”是扭曲的、纠缠的教学迷宫，它将把这些新手变成专家用户。它将一次一次地塑造他们的大脑，直到他们对你的项目如何工作有一个很好的理解。

你通常会希望将“一团乱麻”组织成几个部分（除非这是一个非常小的项目）。这些部分可能_有点_与你的项目的公共 API 中的命名空间对齐，但是当偏离是有意义的时候，你应该这样做。

不要害怕写作。要简洁，但宁可多解释一点。程序员很擅长浏览他们已经知道的东西，但是如果你忘记包含一个关键的连接，它可能会让你的用户迷失方向并在树林里跌跌撞撞。

你应该有一个目录，列出“一团乱麻”的每个部分。然后每个部分都应该有自己的目录，列出其中的各个部分。目录是鸟瞰你即将阅读的内容，为你的大脑做好准备的好方法。当然，它也很方便导航。

这是你的爱好教学练习和阅读《如何解决它》将派上用场的地方。把自己放在用户的脑海中，并弄清楚他们需要做出哪些小的连接飞跃才能成为专家。

第六幕：“阅读 Wiki”

在倒数第二个场景中，一位母亲为她十几岁的儿子报名参加了一个课后驾驶课程。

第一天，老师交给他们一份教学大纲，详细说明他们将要涵盖的内容，谈论评分，并让他们早一点回家。

第二天，她向他们简要概述了汽车的各个部件以及它们如何协同工作。她还谈论了他们需要注意的一些最重要的法律。

第三天，老师请病假，他们有一个代课老师。他涵盖了教学大纲中第五天一半的材料。他必须早点离开，所以他带来了他十九岁的女儿来完成这节课。她涵盖了第四天一半的材料。

第四天，学生们到达后发现门上有一张纸条，说这节课已被取消，因为老师仍然生病，他们找不到代课老师。有一张纸条说“TODO：我们稍后会讨论这些材料。”

第五天，老师部分康复，所以她回来了并涵盖了第五天的材料。很难理解她，因为她喝了半瓶 Nyquil，并且含糊不清地说着大部分单词，并且一直说“猫”而不是“车”。

所有学生都未能通过驾驶考试。

Wiki 是一个可憎之物。它们是“文档”的最糟糕形式。

首先：假设它们按预期工作，它们没有连贯的声音。

你有没有同时上过多个老师的课？可能没有，因为它效果不是很好（除了像合作舞蹈这样有明显引导/跟随部分的事情）。

更糟糕的是：你有没有上过一节课，教室里有一个混蛋不断举手并提供他自己的（通常是不正确的）观点？Wiki 就像那样，除了他们_积极鼓励_随机人员用他们自己的插话来打断老师。

我现在可以听到反对意见：“但是把我们的文档放在 Wiki 上意味着_任何人_都可以修复拼写错误！”

我的天啊。基督。

“这使得修复拼写错误变得容易”是使用 Wiki 的一个可怕的论点。

首先，正如 JKM 所说，你应该有一个编辑（或者至少有人来校对），这将抓住很多拼写错误。

即使_有_拼写错误，它们也是你需要担心的最不重要的事情之一。拼错“他们的”不会对你的教学效果产生太大影响。你的课程因为是由三个不同的人在六个月内编写的而成为一个混乱的局面_将会_使它们的效果降低。

将你的文档保存在 Wiki 中也会使将其保存在它所属的位置变得困难或不可能：与你的代码一起进行版本控制。

但所有这些都是无关紧要的，因为除了 Wikipedia 本身和视频游戏 Wiki 之外，它们根本无法工作。

项目维护者建立一个 Wiki，然后坐下来拍拍自己的后背说：“我已经建立了一种方法，让其他人为我做这项无聊的编写文档的工作。现在我们等待。”

可能有一两个人修复了一些拼写错误。一个认为自己理解一个主题但实际上不理解的人写了一些完全错误的文档。也许它们会被恢复，也许不会。

项目发生了变化。一个新的用户阅读了一些（稀疏的）现在已经过时的文档。最终他们发现了这一点并抱怨，但得到的却是：“好吧，这是一个 Wiki，你自己修复它！”

学生没有责任修复一个损坏的教案。天哪，_拥有老师的全部意义_在于他们知道学生需要学习什么，而学生不知道！

要求你的学生提出批评，以便你可以改进你的教案是完全可以的。询问“你觉得哪些部分很难？”是可以的。要求他们_为你编写你的教案_完全是另一回事。

说真的：去他妈的 Wiki。它们是坏的和可怕的。不要使用它们。花时间和精力编写一些真正的文档。

参考

最后一种类型的文档是“参考”。本节适用于那些已经走过“一团乱麻”并到达另一边的用户。他们现在是你的专家，参考应该在他们日常工作中使用你的项目时支持他们。

本节应包含经验丰富的用户可能需要的内容，例如：

像 JavaDoc 这样的工具可以生成看起来像第一个的东西，但我与 Jacob Kaplan-Moss 持有相同的观点：

自动生成的文档几乎一文不值。充其量，它只是简单地浏览源码的一个稍微改进的版本，但是大多数时候，直接阅读源码比浏览这些自动文档工具产生的废话更容易。每次我点击一个“文档”链接并看到自动生成的文档时，我都会感到一种特别深刻的愤怒。 没有什么可以替代由手工编写、组织和编辑的文档。

是的，你可能会找到一个工具来读取你的项目的源码并吐出一些包含函数名称的 HTML 文件。也许它甚至会包含文档字符串！

我仍然会敦促你手动编写你的 API 文档。这将需要多打一些字，但是出于多种原因，结果会好得多。

API 文档和文档字符串虽然相似，但用途不同。文档字符串必须以一种对 REPL 友好的格式提供你在编码过程中需要的东西。API 文档可以负担得起更多的解释，以及指向用户在浏览它们时可能想要知道的其他东西的链接。API 文档也应该对 Google 友好。

这里一个常见的反对意见是你要重新输入很多单词。复制和粘贴在很大程度上解决了这个问题，而学习打字使剩下的问题不再是问题。

有些人会说：“但是复制和粘贴是邪恶的！你在重复劳动！如果文档字符串和 API 文档中的更改发生变化，你将如何保持它们的同步？”

我的观点是，如果你的面向公众的 API 经常变化，那么当他们需要不断更新他们的代码以与你的代码一起工作时，你可能会让你的用户的生活更加困难。所以你至少可以让你自己的生活稍微困难一点，以便为他们提供最好的文档，以帮助减轻痛苦。

自动生成的文档没有连贯的声音。它会提取代码中的所有内容，而不考虑整体结构和愿景。你_可能_可以为你的“参考”文档中的 API 文档侥幸逃脱，或者你可以对你的工作感到自豪并编写出最好的文档