鉴于 pandas、NumPy 和 Matplotlib 等开源数据科学项目最近的普及，用户对文档的抱怨越来越多也就不足为奇了。为了帮助阐明其中的利害关系，我们与一位对此主题非常了解的人进行了交谈：Thomas Caswell，Matplotlib 的首席开发人员。
Matplotlib 是一款灵活且可定制的工具，用于生成自 2001 年以来的静态和交互式数据可视化，并且是科学 Python 堆栈中的基础项目。Matplotlib 于 2015 年成为 NumFOCUS 赞助的项目。
Tom 在过去的五年里一直致力于 Matplotlib，他的职业生涯始于在 Stack Overflow 上回答关于该项目的问题。回答问题变成了提交错误报告，然后变成了编写补丁，然后变成了维护项目，最终使他成为首席开发人员。
趣闻： Tom 在开源社区的晋升之路完全遵循了核心 Python 维护者 Brett Cannon 描述的道路。
NumFOCUS 通讯主管 Gina Helfrich 与 Tom 坐下来讨论了在一个像 Matplotlib 这样庞大且基础的项目上管理文档的挑战。
Gina Helfrich： Tom，非常感谢您抽出时间与我们讨论 Matplotlib 和开源文档。为了使我们的对话更具体化，您能否谈谈您对 Wes McKinney 在 Twitter 上关于 pandas 以及用户对文档的抱怨的 来回讨论 的印象？
Thomas Caswell： 我只看到了边缘，但我看到了双方。一方面，我认为 Mike Pope 说过，“如果它没有被记录下来，它就不存在。” 如果您正在编写开源工具，
这项工作的一部分是记录它们，并以用户可以发现和实际使用的方式清晰地记录下来，而无需查看源代码。仅仅将代码倾倒在互联网上是不够的——你必须做完整的事情。
另一方面，如果您没有为软件付费，您就不能提出要求。我认为 Wes 正在回应的态度，也是您经常看到的态度是：“您构建了这个对我有用的工具，因此我期望获得企业级付费支持，因为它显然对我正在做的事情至关重要。”
但我认为 Eric O. Lebigot 回应的部分是第一部分。构建工具的一部分是文档，而不仅仅是代码。但 Wes 回应的是权利，是对免费工作的期望，所以我看到了双方。
GH： 看看 Matplotlib，它正面临着与 pandas 相同的许多问题，我知道您的文档面临着一些巨大的挑战。我的印象是，新用户普遍认为 Matplotlib 入门非常令人沮丧，而且文档实际上并没有帮助。您能否谈谈那里的历史，以及该项目是如何产生这个问题的？
TC： 因此，Matplotlib 是一个庞大的库。我已经在这个项目上工作了五年，大约每个月（或每隔一个月），都会有一个错误报告，我的第一反应是，“等等……我们做什么？”
库的很多部分文档不足。这个库至少经历了两次部分转换为标准化文档字符串格式的过程。据我了解（我当时不在），我们是最早采用 Sphinx 构建文档的核心 Python 之外的项目之一——可能有点太早了。由于 Sphinx 当时还没有这些功能，我们有很多奇怪的自定义设置。从那时起，其他人构建了这些功能的更好版本，但由于 Matplotlib 太大了，迁移它们很困难。
我认为，如果您构建我们文档的 PDF 版本，它大约有 3,000 页，而且我会说该库可能只有它真正需要的文档的一半。
从某种意义上说，我们严重文档不足，因为并非每个功能都有好的文档。另一方面，我们又过度文档化，因为我们拥有的文档组织不善，而且没有明确的入口点。如果我想找出如何做某事，即使是我也很难找到文档在哪里。如果我 [首席开发人员] 都难以找到该信息，那么新用户就更不可能找到了。因此，从这个意义上说，我们既严重文档不足，又严重文档过度。
[下一步阅读：系统管理员：糟糕的文档不是一种工作保障策略]
GH： 鉴于 Matplotlib 已经有 15 年以上的历史，您是否了解是谁在编写文档？您的文档实际上是如何开发的？
TC： 从历史上看，就像代码一样，文档是有机开发的。我们在示例和文档字符串方面投入了很多，还有一些标记为教程的条目，教你一项特定的技能。例如，我们有关于“色彩映射的粗略理论”以及如何制作色彩映射的散文。
Matplotlib 的许多文档都是示例，而示例是重叠的。在过去的几年里，当我在邮件列表或 Stack Overflow 上看到有趣的示例时，我会说，“你能把这个示例放在文档中吗？” 所以，我想我一直在积极地促成“内容太多，难以理解”这个问题。
部分问题在于，人们会做一个六小时的教程，然后其中一些示例最终会出现在文档中。然后，其他人又会做一个六小时的教程（你不可能在六小时内涵盖整个库），基本知识可能相似，但他们可能会以不同的方式格式化教程。
GH： 哇，听起来继承和尝试维护起来很有挑战性。您一直在为文档进行哪些改进？
TC： 在过去的几年里，我们一直在努力从我们以前的自制方案转向 numpydoc 格式。此外，Nelle Varoquaux 最近做了大量工作，并领导了从我们过去制作示例的方式转向使用 Sphinx-Gallery 的工作，这使得将好的散文放入示例中变得更加容易。 Chris Holdgraf 最近也采纳了这种做法。 Sphinx-Gallery 在 Matplotlib 2.1 中在我们的主要文档中上线，这对用户来说是一个巨大的改进。 Nelle 还组织了一次分布式 docathon。
我们一直在努力改进新功能。当有新功能时，您必须为该功能在文档中添加示例，这有助于使事物易于发现。我们一直在努力确保文档字符串存在、准确，并且它们记录了所有参数。
GH： 如果您可以挥动魔杖，拥有您想要的 Matplotlib 文档，它们会是什么样子？
TC： 嗯，正如我所提到的，文档是有机增长的，这意味着我们的文档中没有一致的声音。这也意味着各种事情没有单一的事实来源。当您编写示例时，您需要回顾多少基础知识？因此，不清楚在您理解示例之前需要了解什么。要么您只解释足够的知识，一路回顾（所以我们到处都随意散布着基础知识），要么您的示例，除非您已经是高级用户，否则毫无意义。
所以，为了回答这个问题，让一个真正会写作并且对用户有同情心的人通读并写一本 200 页的 Matplotlib 入门书，并使其成为文档的主要入口。这就是我目前想要的愿景。
GH： 如果您今天要向新用户介绍 Matplotlib，您会让她读什么？您会在文档中指向哪里？
TC： 嗯，对于“有人告诉你需要使用 Matplotlib。花一个下午阅读这些内容”来说，没有一个好的、明确的选择。我不确定现在我会把人们指向哪里。 Nicolas Rougier 在这方面写了一些 好的 东西，例如初学者教程，其中一些内容已迁移到文档中。
有很多内容，但没有集中整理，也没有从我们的文档中链接为“从这里开始”。我还应该补充一点，我可能不再对这个问题有最好的看法，因为我没有积极地去寻找这些信息，所以也许我只是从来没有找到它，因为我不需要它。我不知道它是否存在。（这个话题实际上最近在邮件列表中 被提出来。）
我们引导人们去的地方是：查看图库并单击看起来最接近您想要做的缩略图。
Ben Root 在 SciPy 上多次展示了 Matplotlib 解剖教程。存在许多 Matplotlib 书籍。作者是否是该项目的贡献者是混杂的。 Ben Root 最近写了一本关于 交互式图形 的书。有人找过我，我拒绝过几次这项任务，只是因为我没有时间写书。所以我想请一位技术作家来写这本书，而不是将结果作为书出版，而是将其放在在线文档中。
GH： Matplotlib 贡献者社区中是否有人专门负责文档方面的工作，或者对文档承担了很多责任？
Nelle 曾经为 Matplotlib 做过一段时间的文档工作，但现在已经退出了。 Chris Holdgraf 现在正在领导一些与文档相关的工作。 Nicholas Rougier 在项目文档之外编写了许多 非常好的教程。
我的意思是，没有人只使用 Matplotlib。你不会只使用我们而不使用 SciPy、NumPy 或 pandas。您必须使用其他东西来完成您现在需要可视化的实际工作。在其他地方有很多“干净”的 Matplotlib 入门介绍。例如，Jake VanderPlas 的 分析书 和 Katy Huff 和 Anthony Scopatz 的 书 都有 Matplotlib 的介绍，涵盖了他们认为其目的所需的程度。
GH： 我很想听听您对 Stack Overflow 在这一切中的作用的看法。
TC： 这实际上是我进入这个项目的方式。我的 Stack Overflow 数字很大，几乎都是 Matplotlib 问题。我是通过回答问题开始的。 Stack Overflow 上的很多问题都是“请为我阅读文档”。好吧，没问题。但实际上，学习该库的一个好方法是在 Stack Overflow 上回答问题，因为遇到您个人没有的问题的人会问，“我该如何做这个？” 现在您必须去弄清楚如何做。这有点有趣。
但有时人们会提出问题，他们实际上找到了一个错误。在确定他们实际上找到了一个错误之后，我试图弄清楚如何修复错误。所以，我开始写一些报告，这导致了，“这是一个修复我发现的错误的拉取请求。” 然后，当我开始输入大量 PR 时，他们说，“你现在需要开始审查它们了”，所以他们给了我提交权限，让我审查事情。然后他们让我负责。
我确实喜欢 Stack Overflow。我认为在很大程度上，它取代了邮件列表。如果我对 Stack Overflow 有任何批评，我认为那就是说服回答问题的人将更多的结果向上游推送。
Stack Overflow 上有一些很好的例子。这是一个复杂的例子：您必须接触这七个不同的函数，每个函数都有相对完善的文档记录，但您必须以正确的方式将它们组合在一起。其中一些答案可能应该与我们关于它们如何工作的注释一起放在图库中。基本上，如果您浏览 Joe Kington 的前 50 个答案，它们可能都应该放在文档中。
在其他情况下，提出问题是因为文档字符串不清楚。我们需要说服那些回答这些问题的人将这些时刻用作调查我们的文档不清楚的地方，而不是仅仅在 Stack Overflow 上回答，然后将这些答案移回文档中。
GH： 管理文档 PR 与管理补丁和错误修复有什么不同？
TC： 我们试图简化我们处理文档 PR 的方式。编写文档 PR 是开源中最痛苦的事情，因为您会通过拉取请求获得复制编辑。您会通过 GitHub 评论获得挑剔的校对和复制编辑。例如，“缺少逗号”或“两个空格！” 再说一次，我一直把自己当作一个奇怪的异常值基准，当我编写文档拉取请求然后收到 50 条关于挑剔小事的评论时，我感到沮丧。
我已开始尝试将文档的阈值推高到“更改是否使其变得更糟？” 如果没有变得更糟，则合并更改。通常，留下 GitHub 评论比解决问题花费更多时间。
“如果您可以使用 Matplotlib，您就有资格为其做出贡献。”
— Tom Caswell，Matplotlib 首席开发人员
GH： 您希望阅读此采访的社区成员采取一项什么行动？他们可以通过哪一种方式在这个问题上有所作为？
TC： 我希望看到更多的一件事——我承认如何为开源做出贡献是一个很大的障碍——我之前说过，如果您可以使用 Matplotlib，您就有资格为其做出贡献。我想更广泛地传播这个信息。
如果您是用户，并且您阅读了某些内容的文档字符串，但它没有意义，然后您进行了一些尝试并充分理解了该函数以使用它——那么您可以开始澄清文档字符串。
因为我最困难的事情之一是我个人不擅长在编写文档时设身处地为他人着想。我不知道从用户的角度来看——这听起来很讨厌，但我已经深入代码——他们作为新人进入库时知道什么。我不知道在文档字符串中告诉他们哪些正确的事情实际上会对他们有所帮助。我可以尝试猜测，我可能会写得太多，或者写错东西。或者更糟糕的是，我会写一堆指的是他们不知道的东西的东西，现在我只是让这个函数更加令人困惑。
而刚刚第一次遇到此函数的用户，并且弄清楚如何使其实现其目的的用户，正处于正确的思维模式，可以编写他们希望文档所说的内容，这将为他们节省一个小时。
GH： 我认为这是一个很棒的信息。谢谢您与我交谈，Tom！
TC： 不客气。谢谢你。
本文最初于 2017 年发表在 NumFOCUS 博客 上，并且在今天仍然具有同样的意义。经原采访者许可重新发布，并已针对风格、长度和清晰度进行了轻微编辑。如果您想亲自支持 NumFOCUS，请参加在世界各地举办的当地 PyData 活动。在我们的网站上了解更多关于 NumFOCUS 的信息：numfocus.org
1 条评论