文件应由熟练的程序员编写？

Question

我一直认为文档对于项目和团队来说非常重要，应该定期详细地编写。它可以使事情并行，而不必总是向熟练的程序员询问。但我确实发现很多开发人员（甚至是领导者）都没有过多地关注文档而只是把它们视为理所当然，这让我心疼。

我对文件的态度是对的吗？文件真的很重要吗？我应该如何说服团队领导更多地关注这些文件？

如果文件很重要，第二个问题就出现了。 谁应该编写文档？ IMO，它们应该由熟练的程序员编写，比如框架创建者（如果我们使用自己的框架），项目的重要部分（如db schema，整个架构，等等）。

好处是显而易见的，比如帮助新人，帮助维持等等。

因此，从我的观点来看，熟练的程序员（这里的定义可能不同）应该更多地关注文档编写而不是基础结构完成后的代码编写。

我对这一点是对的吗？

感谢您分享这些问题。

Answer 1

您有几种文档，其中一种是您的责任：

在完成时记录每个功能，类，结构，成员

理想情况下，您可以通过允许自动提取源文档（例如Doxygen）的方式执行此操作。请务必随时随地进行。

就客户文件而言，我的信念是：

• 每家开发公司都应聘请测试人员
• 测试人员应为文档编制过程做出重大贡献

我一直与那些不会全额支付最终产品的公司合作，除非它附带完整而全面的文档。通常会扣留10％，以确保承包商有动力提供所有材料。

就测试人员而言，他们真的是你最好的朋友（或应该是）。他们是那些知道您的软件如何工作的人。是的，我同意，你应该至少有一个程序功能的大纲，这可以让你不再使用'增值'切线。让测试人员成为填写此内容的人是有意义的，然后让开发人员对其进行审查以确保准确性。

你甚至可能会发现你的自我说“不不不......它不会那样工作......测试人员弄错了...... ”，然后启动应用程序以实现他们做对了:)在这方面，它对QA过程也有帮助。

Answer 2

我认为这取决于每个团队，但很多时候，程序员并不擅长编写文档。这就是为什么有人喜欢技术作家。程序员应该参与每一步，因为他们是主题专家，但作者应该写。

Answer 3

您的小组应该创建一个软件开发流程，定义您如何开发软件产品。该过程的一部分将定义要编写的文档，根据我的经验，开发团队的所有成员都在文档过程中共享 - 它可以（并且应该）是一个学习过程。

您的软件开发过程也应该定义其他主题，例如代码审查，单元测试，配置管理等。

网上有很多流程的例子，从非常轻到重。

Answer 4

要询问任何潜在文档的重要问题是文档的目标，预期用途和预期使用频率是多少？你提到帮助一个新人，但实际上，从其他开发人员那里获得演练是否更快，更有效地阅读文档？演练需要时间从其他开发人员那里获得，但写文档的时间可能要少得多。

具有强大商业案例和替代选项的投资回报率的文档对于创建是有意义的，但是您可能想到的情况可能更少，并且在没有对我的初始问题做出明确答案的情况下创建文档将保证您不会获得投资回报率。

Answer 5

你没错，但事实是文档不能赚钱。如果有的话，糟糕的文档可以增加收入，因为您已经确保客户需要您的支持合同。

文档也很痛苦，因为理论上它应该在开发之前完成，但实际上事情发生了变化，因此在主要版本之后创建/更新真的值得释放。

理想情况下，作者应该是业务分析师，不开发人员。

Answer 6

查看文档的另一种方法是用于CYA目的。如果你不幸遇到一个项目，领导层没有生成文档，那么错误代码的责任可以归咎于你。除非你用文件保护自己。

Answer 7

最能说出客户语言的人是应该撰写文档的人，即使他们不是最了解产品的人。他们应该与最了解产品的人交流，但文档不是关于编码能力的;这是关于沟通的。

如果您不善于沟通，那么您对产品的了解程度无关紧要，您的文档将毫无用处。