业界对文档的厌恶是什么？

即使编写最基本的文档，似乎也存在反感。我们的项目自述文件是相对裸露的。在文档中甚至没有更新的依赖项列表。

我在行业中没有意识到让程序员不喜欢编写文档的东西吗？如果需要，我可以键入文档的段落，那么为什么其他人那么讨厌呢？

更重要的是，我如何使他们相信写文档会为我们节省时间和日后的挫败感？

我认为推测那些没有采用您认为是好的做法的人或正在继续做您认为不好的事情的人的动机没有帮助。在这项业务中，属于这两个类别中的一者或两者的人将远远超过与您会面的人，因此不要让自己发疯。

相反，请专注于问题和可能的解决方案。

1.自己编写好的文档

期望团队中的每个人都将精力放在您认为是问题上的事情可能是不现实的。如果您是该团队的新手，则尤其如此。我敢猜测您是，因为如果您是团队的创始成员，您似乎很可能早就解决了这个问题。

相反，考虑实现自己编写好的文档并使人们使用它的目标。例如，如果团队中的某人问我项目A的源代码在哪里或项目A需要什么特殊配置，我可以将他们指向项目A Wiki页面。

如果有人问我如何编写Factory F的新实现以为Client C定制事物，我告诉他们是在开发人员指南的第10页上。

大多数开发人员讨厌问一些问题，这可能会使他们看起来不仅只是“阅读代码”而不是讨厌阅读文档。因此，在经过如此性质的足够答复之后，他们将首先阅读文档。

2.证明文件的价值

确保您抓住一​​切机会指出文档在哪里证明了它的价值（或如果有的话，将具有证明价值）。尽量保持微妙，避免使用“我曾告诉过你”，但是说些类似的话是完全合法的

为了将来参考，该项目的Wiki页面包含有关为持续支持版本2.1而创建的核心代码分支的信息，因此，如果维护发布版本的人员进行了检查，将来我们可以避免进行完全的回归测试。签出代码之前先查看Wiki。

要么

我很高兴写下了执行任务T的步骤。我真的不在乎是否没有其他人使用它-它已经为我节省了比编写它更多的时间。

3.做好管理工作

在发生了一些事后可以证明节省时间/金钱的事件之后，您可能会注意到对文档的一种独特的“解冻”。现在是时候开始在评估中包括文档时间了（尽管老实说，我通常会在较长的进程（例如编译或签入）运行时更新/创建文档）来达到目的。尤其是如果这是最近招聘的员工，可能不会对此提出质疑，而是将其视为您从以前的工作场所引进的新做法（这很可能是）。

忠告：大多数老板都不愿意让人们做任何事情，尤其是与可计费任务没有直接关系的事情，因此不要指望这种支持会以强制性的形式出现。相反，它更有可能让您自由地编写更多文档。

4.鼓励您看到文档

人们不经常写文档的部分原因可能是他们觉得没有人在阅读文档。因此，当您看到自己喜欢的东西时，请确保至少提及您对它的可用性感到高兴。

如果您的团队进行代码审查，那么此时您可以输入一两个字来鼓励良好的评论。

感谢您在Framework G中记录错误B的解决方法。我对此一无所知，而且我认为如果没有该工具，我无法理解您的工作。

如果您的团队中的某个人实际上对文档充满热情，那么通过午餐或喝咖啡来培养这个人并确保提供一点验证以抵消他们因看到团队中的其他成员而产生的挫败感并没有什么害处。对文档的重视程度不高。

除此之外，除非您担任领导或管理职位，否则这实际上不是您的问题。您可以将一匹马带到水上，但不能让它喝水。如果不是您的马，您可能会不满意它的口渴，但您所能做的就是填满食槽。

我的经验有两个主要因素：

截止期限

大多数公司太过追求日期，以至于削减了质量保证，技术债务和实际设计，这样项目经理就不会看起来很糟糕，也不会遇到一些荒谬的，过分承诺的客户期限。在这样的环境中，甚至功能质量也被削减，因此像文档这样的长期投资几乎没有机会。

更改

对于开发人员而言，相对较新的最佳做法是取消强调注释。这样做的想法是，将信息保存在两个位置（代码（包括测试）和代码周围的注释）会导致大量开销，导致它们保持同步，而收效甚微。“如果您的代码难以阅读而需要注释，那么花时间清理代码会更好吗？”

我个人甚至不会再评论。代码不能撒谎。

文档遵循同样的思路。随着敏捷的广泛采用，人们认识到需求会定期更改。随着重构的广泛使用，代码的组织将发生相当大的变化。为什么花时间记录所有这些必将改变的东西？代码和测试应该做得很好。

这里有许多因素在起作用：

1. 编写良好的代码是其自己的文档。在其他所有条件都相同的情况下，最好编写能说明问题的清晰代码，而不是编写更多文档。这样做，当您更改该代码时，您将需要修改较少的文档。

2. 编写文档可以说是与编写代码不同的技能。一些软件开发人员比其他软件开发人员更好。有些人在编写代码方面比编写文档要好得多。

3. 文档只需要编写一次，而不是两次（在源代码中一次，在程序员指南中一次）。这就是为什么我们需要XML注释和文档生成器之类的原因。不幸的是，使用这些工具比手工编写文档更加棘手和麻烦，这就是为什么您看不到这些工具被广泛使用的原因。

4. 好的文档非常耗时，而且很难做好。在其他所有条件都相同的情况下，编写新代码比为已有代码编写文档更具价值。

5. 当代码更改时，您还必须更改文档。文档越少，需要更改的内容就越少。

6. 无论如何，没人会阅读文档，那么为什么要打扰呢？

房间里的大象：程序员不是（不一定）是作家。它们也不一定适合向技术作家充实其实现。房间里的第二象：技术作家通常无法充实对将来的开发人员有用的细节（即使开发人员愿意向他们解释）。

如果没有适当的文档说明，随着时间的推移，复杂的系统将变得难以理解。与它的可扩展性[sic]成反比，该代码的价值变得越来越小。解决后，管理层聘用了软件工程师，他可以从开发人员那里读取代码和同轴电缆详细信息，以开发人员的价格向他付款，并授权他进行文档编制和维护文档。该作者可以阅读代码，并且知道要问什么问题，并根据需要填写详细信息。就像您有一个质量检查部门一样，您也有一个内部文档部门。

该代码将变得更有价值，因为您可以将其许可给第三者（因为他可以理解），因此可以更轻松地对代码进行审核和改进/重构，即使在您可以轻松访问的地方，代码也可以更好地重用剔除软件的轻量级版本，您将能够更轻松地将新开发人员引入该项目，您的支持工程师将很乐意为您工作。

这将永远不会发生。

更重要的是，我如何使他们相信写文档会为我们节省时间和日后的挫败感？

这样做吗？

有两种类型的文档：

有用的文件

记录如何使用成品，API，服务器的IP地址或URL名称等。基本上，所有日常使用的东西都很繁琐。错误的信息将很快被发现并得到纠正。需要被发现易于编辑（例如在线Wiki）。

无用的文档

文档经常更改，很少有人对此感兴趣，而且没人知道在哪里可以找到它。就像正在执行的功能的当前状态。或隐藏在SVN中某个地方的word文档中的需求文档，该文档已于3年前更新。该文档将花费一些时间来编写，并且稍后需要花费时间来发现它是错误的。您不能依靠这种类型的文档。这没用。浪费时间。

程序员不喜欢编写或阅读无用的文档。但是，如果您可以向他们展示有用的文档，他们会编写它。在引入Wiki时，我们在上一个项目中取得了成功，我们可以在其中编写经常需要的所有信息。

我要说的主要原因是缺乏意志和对文件功能的理解。有许多类文档可供考虑：

产品/发行文件

这是您的“成品”产品所不具备的。这不仅仅是手册，还包括自述文件，更改日志，HOW-TO等。从理论上讲，您可以不用编写这些代码而逃不过一劫，但最终会得到人们不希望使用的产品，或者不必要地增加了昂贵的支持负担。

API文档

这描述了应该是相对静态的东西。由于可能有许多使用者使用您的API进行编码，因此它应该足够稳定，以至于一些描述如何使用它的散文都具有价值。描述支持哪些参数，可以返回的值以及可能引发的错误将使其他用户能够在正确的抽象级别（接口（而不是实现））理解您的API 。

代码注释

目前，业界对评论的意见似乎在不断变化。当我第一次开始专业编程时，注释是编写代码的必要条件。现在，时尚是编写如此清晰的代码，而无需注释。我可能会猜测，部分原因是由于许多现代语言的编写水平更高，而且用Java，JavaScript，Ruby等语言编写清晰的代码比在汇编器中编写起来更容易，C，FORTRAN等。因此，注释具有更大的价值。

我仍然相信，在描述部分代码的意图的注释中还是有价值的，或者是有关为什么选择某种算法而不是一种显而易见的算法的一些细节（以避免过分热衷于将“固定”代码重构为“恶意”）。 t实际上需要修复）。

不幸的是，程序员在决定不记录时有很多自私，合理化和自欺欺人的行为。现实情况是，与代码一样，文档的主要受众是其他人。因此，在任何级别上写（或不写）文档的决定都是应该在团队级别做出的。对于更高级别的抽象，让开发人员以外的人来做可能更有意义。至于评论级别的文档，应共同就评论的目的和意图达成一致，尤其是在能力和经验混合的团队中。让高级开发人员编写初级开发人员无法接近的代码是不好的。一些位置适当且书面明确的文档可以使团队更有效地运作

这是我的两分钱。

1. 敏捷宣言指出“在综合文档中使用软件”，而并非每个人都会继续读下去，“也就是说，尽管右侧的项目有价值，但我们更重视左侧的项目。”

2. 遗憾的是，https： //en.wikipedia.org/wiki/Code_and_fix很常见，并且该文档不适用于此模型（它不同步）。

3. 软件开发行业监管不力。没有法律要求编写文档。

4. 自记录代码是当前的趋势。

话虽如此，我认为那里有很多很好的文档。

文档编写需要时间，我怀疑很多开发人员的文档运行过多，比没有用的糟糕。他们的想法是，不仅文档会给他们的经理（一直削减计划中的质量检查部分的那个人）带来麻烦，而且对任何人（包括他们）都没有帮助。

任何体面的文件记录都是对未来的投资。如果您不关心未来（因为您不考虑下一份薪水，或者因为您认为这不会成为您的问题），那么编写文档的想法将非常痛苦。

许多其他答复掩盖了至少有两种类型的文档：一种是针对其他开发人员的文档，另一种针对最终用户的文档。根据您的环境，您可能还需要系统管理员，安装人员和帮助台人员的其他文档。每个目标受众都有不同的需求和理解水平。

考虑一下（立体）开发人员：他是一名选择的编码人员。他从公众的视野中选择了职业，并且主要在与自己进行交流的键盘后面度过了很长时间。文档编制过程是一种沟通形式，而生成良好文档所需的技能与生成良好代码所需的技能相反。

一个好的文档编写者可以使用多种语言进行交流：用户的语言，管理的语言，支持人员的语言，开发人员的语言。文档编写者的工作是了解编码人员所传达的内容，并将其转换为所有其他小组都可以理解的形式。

当您期望编码人员发展成为良好的沟通者（书面或其他）所必需的技能时，磨练主要技能集（编码！）所花费的时间会减少。他离舒适区越远（与其他编码人员进行编码和通信），则需要更多的时间和精力来很好地完成任务。您可以合理地期望专业编码人员希望主要专注于其核心能力，而却要牺牲所有其他能力。

因此，文档（内联代码注释除外）最好留给沟通者，而不是程序员。

阅读代码将向您展示其工作方式。它无法解释原因：您需要评论。

读取代码将为您显示方法的名称和参数的类型。它无法解释语义或作者的确切意图：您需要评论。

注释不会代替阅读代码，而是添加了代码。

文档未按代码执行。结果，通常没有有效的反馈循环来验证文档是否到位并完整。这与代码注释倾向于腐烂的原因相同。

Donald Knuth提倡Literate Programming，以提高软件质量，有效地编写带有代码的文档。我看到一些项目非常有效地使用了这种方法。

我个人试图保持现代趋势，即保持代码的公共API尽可能可读，并使用单元测试来记录其他开发人员的使用情况。我认为这是使您的API具有可以探索和发现的形式的更大想法的一部分。我认为这种方法是HATEOAS试图通过Web服务实现的一部分。

这是一个很小的要点，但对于一些编写令人讨厌的小文档的开发人员来说，这似乎很重要：他们无法键入。如果您大致了解10指系统，则往往会因为简单而编写更多文档。但是，如果您坚持狩猎和啄食，就会迷路。如果我要负责招聘，那实际上是我要检查的事情。

不喜欢阅读文档的人不喜欢编写文档。为避免彻底阅读文档，许多程序员将竭尽所能。

不要专注于写作，专注于阅读。当程序员阅读文档并将文档中的内容吸收时，他们将看到其价值，并且更倾向于编写文档。

当我开始目前的工​​作并从以前从事该项目的人员那里接手了一个硬件和软件项目时，得到了一百页左右的描述该系统的ms word文档。生产必须花几天的时间。我看了两次。尽管其中包含大量信息，但是它很少回答我对系统的实际问题，即使这样做，也可以更快地查看代码。

经过足够的经验之后，您才开始思考，为什么要打扰？为什么要花时间回答人们从未问过的问题？您开始意识到预测人们将在文档中寻找的信息是多么困难。事实不可避免地充满了事实，这些事实变得毫无用处，不清楚或显而易见，并且缺乏最紧迫问题的答案。请记住，提供有用的文档是在预测人类行为方面的一项工作。就像用户界面设计在经过多次测试和调试迭代​​之前不太可能成功一样，因此天真的认为仅根据人们对系统的理解以及期望的内容编写有用的文档是可能的。文档及其语言将在该解释中扮演的角色。

我倾向于认为编写文档的大部分压力来自这样一个事实，即这是一件令人不快的琐事，人们喜欢内like地彼此做不愉快的琐事（“您还没有吃过腓肠肌的lb脚！”）。

然而

我并不认为文档在所有方面都是绝望的。我认为这主要是无望的，主要是因为人们将文档视为完成工作之前必须完成的额外负担，作为匆忙完成的最后清理工作以及作为检查框的工作。文档是您应该始终进行的日常工作。我认为电子邮件是做文档的一种特别好的方法。添加新功能时，给几个人写一封简短的电子邮件，说明它的含义。绘制新原理图时，生成PDF并将其发送给可能感兴趣的任何人。电子邮件的优点是：

1. 人们通常会检查电子邮件，而没人会涉足名为“ doc”的文件夹。

2. 电子邮件存在于上下文中，周围是讨论该功能和相关功能以及当时发生的任何其他事情的其他电子邮件。

3. 电子邮件简短简短，主题明确。

4. 电子邮件允许关心的人立即提出问题，

5. 电子邮件是高度可搜索的，因为人们将其用于所有内容，并且这些年来，邮件客户端已经有了长足发展。

6. 如果在电子邮件中，则至少有另一个人知道在哪里可以找到它。

从理论上讲，代码中的注释似乎也应该是“无论如何都需要注意的一天”，但是老实说，我从不阅读代码中的注释。我不知道为什么，但是它们并不是很有用，可能是因为缺少可以解决电子邮件的上下文。