为什么这么多图书馆没有/缺少文档？[关闭]

与没有项目设计或体系结构文档的开源项目如何成功一样？问题，我很好奇：为什么如此众多的库缺少最终用户文档？

我的看法是这样的：

1. 大多数人都认为阅读源代码比编写源代码更困难。
2. 如果没有文档，则必须阅读该库的源代码才能使用该库。
3. 因此，使用未记录的库比从头开始重新创建库要耗费更多的工作。
4. 因此，如果您想让人们使用您的图书馆，那么最好确保它已被记录在案。

我知道许多开发人员不喜欢编写文档，并且我同意这可能是乏味的工作。但这是必不可少的工作。我什至要说，拥有一个好的文档比拥有世界上最好的程序员接口更重要。（人们一直使用糟糕的库；很少使用未记录的库）

哦，请注意，当我说文档时，是指真实的文档。不是Sandcastle / Javadoc / Doxygen样板。

我认为您基本上已经回答了自己的问题：因为在大多数情况下，开发人员不会打扰。这个问题在志愿者项目中尤为普遍。

我确实认为还有另一个主要问题：在很多情况下，开发人员并没有真正开发出有关其库工作方式的整体模型（或者很难清楚地阐明该模型）。不幸的是，阐明该模型以及软件各部分之间的配合方式通常是文档中最重要的部分。

在典型情况下，所编写的内容具有非常高级的概述（“这是一个很棒的库！”），然后具有非常低级的描述（要传递给每个函数的每个参数的类型和描述）。不幸的是，关于事物应该如何工作，各个部分如何组合等的一般理论很少有中等水平。这在很大程度上可以回溯到这样一个事实，即开发人员经常没有尝试形成，合理化或理解其内容。特定细节级别的代码。至少在我看到的某些情况下，被要求在该级别编写文档的开发人员发现它很成问题-以至于许多人都希望重写代码，以便在该级别上更加井井有条，更易于解释。详情。

在这样的抽象级别上编写好代码通常很困难-如果开发人员没有在那个抽象级别上真正考虑过代码开发，他们常常会觉得代码有些尴尬，并且可能想在满意之前重写代码关于释放它。

我认为有时候是因为开发人员太沉迷于代码中，以至于他/她“很明显”知道代码的工作方式，因此他们看不到为什么其他人看不到它。同样，大量的产品网站说明了他们的产品多么出色，但实际上并没有告诉您它的用途！

您自己指出了答案：

我知道许多开发人员不喜欢编写文档，并且我同意这可能是乏味的工作。

作为程序员，我们喜欢编写代码，但是很少有人喜欢编写文档。

尽管任何优秀的编码人员都知道好的文档的价值，但正确地花费大量的时间。由于它不愉快且需要很长时间，因此将其放入“以后再做”堆中，因此永远无法达到令人满意的水平。

附带说明一下，程序员也很难在自己的产品上编写文档。正如他们对系统的了解一样，某些事情对他们来说很明显。尽管对消费者而言并不明显，但这些部分通常从未被提及。

编写文档是一种技能。像所有技能一样，它也需要练习。我们花费在编写代码上的时间和精力可以立即得到回报。我们可以看到新功能，已修复的错误和提高的速度。编写文档会有延迟的收益。从长远来看，这对新人来说是有帮助的，因为他们需要编写代码，或者如果我们几个月或几年后又回到代码上工作。我们专注于短期是很自然的。

在我看来，编写好的文档的能力是区分优秀程序员和普通程序员的关键特征之一。

最有资格编写文档的人也是这样做动机最小的人：

他（或她）是：

• 主要是库的维护者，而不是用户。因此，库越小越简单，他的工作就越容易。除了编写代码外，还要保留半本小说，只会使他的工作更加艰辛，
• 他完全了解图书馆，所以他不需要文档，
• 他是一名程序员，他想编写代码，而不是文档。

我想不出任何人谁是不太可能去“嗯，我真的应该花几个小时写一些适当的文件，此”。他怎么会

当然，这可能对都市传说无济于事，自动生成的Doxygen式注释是您在文档方面所需要的。

因此，即使在极少数情况下开发人员实际上愿意编写文档，也有50/50的机会被这种邪教洗脑，认为所需要的只是填写一些这样的注释，告诉您像“该函数Foo getFoo()返回一个Foo类型的对象，并用于获取Foo对象”。

文档？我们不需要臭气熏天的文档！

我知道代码的工作原理，那么为什么要花时间记录我的代码？除此之外，我必须在星期五之前完成这个项目，而我几乎不会按原样进行...