项目中的难点怎么克服_克服大型项目中的文档挑战

项目中的难点怎么克服

鉴于最近熊猫（ Pandas） ，NumPy和Matplotlib等开放源数据科学项目的普及Swift增长，人们对文档的兴趣日益浓厚 ，这不足为奇。 为了帮助您了解所面临的问题，我们与Matplotlib的首席开发人员Thomas Caswell进行了交谈。

自2001年以来，Matplotlib是一个灵活且可自定义的工具，用于生成静态和交互式数据可视化，并且是科学Python堆栈中的基础项目。 Matplotlib于2015年成为NumFOCUS赞助的项目 。

Tom在过去的五年中一直在研究Matplotlib，并开始回答有关Stack Overflow项目的问题。 回答问题后提交了错误报告，并编写了补丁程序，从而维护了项目，最终使他成为首席开发人员。

有趣的事实： Tom在开源社区中的进步完全遵循了Python核心维护者Brett Cannon所描述的道路 。

NumFOCUS传播总监Gina Helfrich与Tom进行了座谈，讨论了管理像Matplotlib这样庞大而基本的项目中的文档所面临的挑战。

Gina Helfrich：非常感谢您抽出宝贵时间与我们讨论Matplotlib和开源文档，Tom。 为了使我们的对话更加具体化，您能否与Wes McKinney在Twitter上对熊猫的来回印象以及对文档的用户投诉谈一下？

托马斯·卡斯韦尔（T​​homas Caswell）：我只看到了边缘，但看到了两侧。 一方面，我认为迈克·波普（Mike Pope）说的一句话是：“如果没有记录，就不存在。” 如果您正在编写开源工具，

另一方面，如果您不付钱（购买软件），就不会提出要求。 我认为Wes对此的React是，您经常看到的态度是：“您构建了对我有用的工具，因此，我希望获得企业级的有偿支持，因为这显然对我的工作至关重要。”

但我认为Eric O. Lebigot响应的部分是第一部分。 建立工具的一部分是文档，而不仅仅是代码。 但是，韦斯（Wes）正在回应应享的权利，即对自由工作的期望，因此我看到双方。

GH：专门研究Matplotlib，它面临着与熊猫相同的许多问题，我知道您的文档面临一些巨大的挑战。 我给新用户留下的印象是，开始使用Matplotlib非常令人沮丧，并且文档并没有真正的帮助。 您能告诉我那里的历史以及该项目如何出现这个问题吗？

TC：因此，Matplotlib是一个庞大的库。 我已经进行了五年的研究，大约每月一次（或每隔一个月一次），有一个错误报告，我的第一个React是：“等等……我们做什么 ？”

许多图书馆文献不足。 该库至少经历了两代到标准docstring格式的部分转换。 据我了解（当时我不在），我们是核心Python之外第一个采用Sphinx来构建我们的文档的项目之一-可能为时过早。 由于Sphinx [当时]还没有这些功能，因此我们有很多奇怪的自定义设置。 从那时起，其他人就为这些功能构建了更好的版本，但是由于Matplotlib如此庞大，因此很难移植它们。

我认为，如果您构建我们文档的PDF版本，则大约有3,000页，我想说该库可能只有其真正需要的文档的一半。

并不是每个功能都有好的文档，就意味着我们的文档不足。 另一方面，我们文档过多，因为我们所拥有的东西组织得不好，没有明确的切入点。 如果我想知道如何做某事，即使我也很难找到文件记载的地方。 而且，如果我 （首席开发人员）在找到该信息时遇到问题，那么就不会有新用户祈祷。 因此，从这个意义上讲，我们既没有充分记录在案，也没有太多记录在案。

[下一篇： Syadmins：不良文档不是工作保险策略 ]

GH：鉴于Matplotlib已有15年的历史了，您是否了解谁在编写文档？ 您的文档实际上是如何开发的？

TC：从历史上看，就像代码一样，文档是有机开发的。 我们在示例和文档字符串上进行了大量投资，还有一些标记为教程的条目可以教您一种特定技能。 例如，关于“颜色图的粗糙理论”以及如何制作颜色图的文章，我们已经发表了。

Matplotlib的许多文档都是示例，这些示例相互重叠。 在过去的几年中，当我在邮件列表或Stack Overflow上看到有趣的示例时，我会说：“您可以将此示例放入文档中吗？” 因此，我想我一直在积极地参与解决太多问题的问题。

问题的一部分是人们将进行六个小时的教程，然后其中一些示例最终出现在文档中。 然后，其他人将进行一个为时六个小时的教程（您不可能在六个小时内覆盖整个库），并且基础知识可能相似，但是他们对教程的格式可能有所不同。

GH：哇，继承和尝试维护听起来很困难。 您正在为文档进行哪些改进？

TC：过去几年来，人们一直在努力转向numpydoc格式，而不是以前使用的本地计划。 另外， Nelle Varoquaux最近做了大量工作，并带领工作从我们的示例方式转变为使用Sphinx-Gallery，这使得将良好的散文撰写到示例中变得容易得多。 Chris Holdgraf最近也采用了这种做法。 Sphinx-Gallery使用Matplotlib 2.1在我们的主要文档中上线，对用户而言是一个巨大的进步。 内尔（ Nelle）还组织了一次分布式招待会 。

我们一直在努力使新功能变得更好。 有了新功能时，您必须在该功能的文档中添加一个示例，以帮助发现问题。 我们一直在努力确保文档字符串存在，准确并记录所有参数。

GH：如果您可以挥动魔杖并拥有所需的Matplotlib文档，它们会是什么样？

TC：嗯，正如我所提到的，文档是有机增长的，这意味着我们之间没有一致的声音。 这也意味着各种事情没有单一的真理。 当您编写示例时，您对基础知识的了解还差多少？ 因此，在理解示例之前，尚不清楚需要了解什么。 您可以一直讲到足够的解释（这样我们就可以在各处涂抹各种基础知识），或者您有一些示例，除非您已经是沉重的用户，否则就没有任何意义。

因此，要回答这个问题，请一个真正可以写并且对用户有同情心的人审阅并撰写一份200页的Matplotlib书籍简介，并将其作为文档的主要内容。 那就是我目前对自己想要的东西的看法。

GH：如果您今天向Matplotlib引入了一个新用户，那么她会读到什么？ 您会在文档中指出她什么地方？

TC：嗯，没有一个好的明确选择，“已经被告知您需要使用Matplotlib。请花一个下午的时间阅读此书。” 我不确定现在该指向人们指向何处。 Nicolas Rougier在这方面写了一些不错的 东西 ，例如面向初学者的教程，其中一些已经移植到了文档中。

那里有很多东西，但是没有集中整理，或者从我们的文档链接为“ START HERE”。 我还应该补充一点，因为我还没有主动去寻找这些信息，所以我可能再也没有最好的了解了，所以也许我只是因为找不到它而从未找到它。 我不知道它的存在。 （实际上，该主题最近出现在邮件列表中。）

我们将人们指向的地方是：去画廊，然后单击看起来最接近您想要做的缩略图。

Ben Root多次在SciPy上展示了Matplotlib的解剖学教程 。 有许多Matplotlib书籍。 作者是否是[项目]的贡献者参差不齐。 本·鲁特（Ben Root）最近写了一篇有关互动人物的文章 。 已经联系了我，并且几次拒绝了此任务，只是因为我没有时间写书。 因此，我想聘请一名技术作家的想法是让一名技术作家来撰写这本书，而不是将结果发布为书籍，而是将其放入在线文档中。

GH： Matplotlib贡献者社区中是否有人专门研究事物的文档部分，或者对文档拥有很多所有权？

内尔（Nelle）为Matplotlib做了一些，但后退了一步。 克里斯·霍尔德格拉夫（Chris Holdgraf）现在正在领导一些与文档相关的事情。 Nicholas Rougier在该项目的文档之外写了许多非常好的教程 。

我的意思是，没有人仅使用Matplotlib。 您不使用我们，但不使用SciPy，NumPy或熊猫。 您必须使用其他方法来完成现在需要可视化的实际工作。 在其他地方，有许多关于Matplotlib的“简洁”介绍。 例如，杰克·范德普拉斯（Jake VanderPlas）的分析书以及凯蒂·霍夫（Katy Huff）和安东尼·斯科帕兹（Anthony Scopatz）的书都对Matplotlib进行了介绍，涵盖了他们认为达到其目的所需的程度这一主题。

GH：我很想听听您对Stack Overflow在所有这些方面的作用的看法。

TC：实际上，这就是我进入该项目的方式。 我的堆栈溢出数很大，几乎是所有Matplotlib问题。 而我的上手方式是我回答了问题。 关于堆栈溢出的许多问题是：“请为我阅读文档。” 好的 但是实际上，学习该库的一种好方法是回答有关Stack Overflow的问题，因为遇到您本人没有的问题的人会问：“我该怎么做？” 现在您必须找出解决方法。 很好玩。

但是有时人们会提出问题，而实际上却发现了一个错误。 在确定他们确实找到了错误之后，我试图找出如何修复这些错误。 因此，我启动了一些报告，结果是，“这是一个修复我发现的错误的请求”。 然后，当我开始输入许多PR时，它们就像是“您需要立即开始审阅它们”，因此它们赋予了我提交权限，并使我可以进行审查。 然后他们让我负责。

我喜欢堆栈溢出。 我认为在很大程度上，它取代了邮件列表。 如果我对Stack Overflow有任何批评，我认为这可以说服正在回答更多问题的人。

关于堆栈溢出有一些很好的例子。 这是一个复杂的过程：您必须触摸这七个不同的功能，每个功能都有相对完善的文档，但是您必须以正确的方式将它们组合在一起。 其中一些答案可能应该与我们有关其工作方式的注释一起放入图库中。 基本上，如果您浏览了Joe Kington的前50个答案，那么它们可能应该全部都包含在文档中。

在其他情况下，由于文档字符串不清楚，因此会提出问题。 我们需要说服正在回答这些问题的人，利用这些时间来调查我们的文档尚不清楚的地方，而不是仅仅回答[Stack Overflow]，然后将这些答案移回[docs]。

GH：管理文档的PR（而不是补丁和错误修复）感觉如何？

TC：我们试图简化文档PR的方式。 在开放源代码中编写文档PR是最痛苦的事情，因为您可以通过请求请求进行复制编辑。 您可以通过GitHub评论进行挑剔的校对和复制编辑。 例如，“缺少逗号”或“两个空格！” 再次，我继续使用自己是一个奇怪的异常基准，当我写的文档引入请求我灰心丧气，然后我得到关于挑剔的小东西50个评论。

我开始尝试推动文档的门槛是：“ [更改]会使情况变得更糟吗？” 如果情况没有恶化，请合并更改。 通常，留下GitHub评论要比解决问题花费更多时间。

“如果可以使用Matplotlib，则有资格为它做贡献。”
-Matplotlib首席开发人员Tom Caswell

GH：您希望正在阅读本采访的社区成员采取什么措施？ 他们可以在这个问题上有所作为的一种方式是什么？

TC：我想看到更多的东西-我承认如何为开源做贡献是克服挑战的一大障碍-我之前已经说过，如果您可以使用Matplotlib，您就有资格为它做贡献。 这是我想更广泛宣传的信息。

如果您是用户，并且在某种程度上读了文档字符串，那么这没什么意义，然后您会进行一些尝试，并且充分了解该功能以使用它—然后可以开始澄清文档字符串。

因为我最难熬的一件事是，我个人在编写文档时不擅长将自己摆在别人的面前。 从用户的角度来看，我不知道-这听起来令人讨厌，但我对代码的了解足够深-他们知道以新手身份进入图书馆的情况。 我不知道在文档字符串中告诉他们实际上对他们有帮助的正确方法。 我可以尝试猜测，可能会写太多或写错东西。 或更糟糕的是，我会写很多东西来指代他们不知道的事情，而现在我只是使函数变得更加混乱。

初次接触此功能并理清如何使其实现其目的所需的功能的用户，正以正确的心态写出他们希望文档所说的本来可以节省的功能他们一个小时。

GH：我认为这是一个很好的信息。 感谢您与我交谈，汤姆！

TC：不客气。 谢谢。

本文最初于2017年在NumFOCUS博客上发布，今天也是如此。 经原始面试官的许可，此书已重新发布，并对其样式，长度和清晰度进行了轻松编辑。 如果您想亲自支持NumFOCUS，请参加世界各地发生的本地PyData事件之一。 了解更多关于NumFOCUS在我们的网站： numfocus.org

翻译自: https://opensource.com/article/19/11/documentation-challenges-tom-caswell-matplotlib

项目中的难点怎么克服