谁应该写技术文档？

Question

起初，我认为编写代码的人也应该把它记录下来。但是，有一些理由可以解释为什么这可能不是真的。一个人，谁是新的守则可以提出正确的问题，可能会被认为是“显而易见”的作者。

我的问题是，如果有既定的做法(或做法)，其背后的理由是什么？

Answer 1

听起来像是在假设文档只编写一次而从未更新过。如果您的软件在编写之后从未更改，这可能是正确的，但情况可能并非如此。就像您可以重构您的代码以提高可读性和可维护性一样，您的文档也应该是一种促进重构能力的格式。您的初始代码作者是编写初始文档的好人选，但是维护代码的人员也需要维护文档。如果现有的作者仍然存在，并且正在回答新的维护人员的问题，那么应该为某人(原始作者或新的维护者)分配任务，确保文档更加完整。

角色和责任的确切分类取决于组织。在某些地方，开发人员负责代码文件中的任何内容(API文档和在线注释)，开发人员和测试人员支持编写和维护文档的技术编写人员。在其他组织中，开发团队可以编写所有东西。

说到底，谁编写和维护文档并不重要，只要文档被维护就行了。毕竟，错误的文档可能比根本没有文档更糟糕。

Answer 2

在我的经验中，文档最大的问题是，它通常不画出重要的图片，它会列出一个高级别的模型，然后放大。如果让开发人员编写文档，就会重复使用自然语言编写的代码，这对其他开发人员和用户都是毫无意义的。文档应在分析和设计过程中由分析人员和设计人员编写，而不是由输入代码的人员事后考虑。如果你幸运的话，是同一个人，他不太真实，也有一定的想象力。不幸的是，在项目被标记为已完成之前，文档通常是某些人必须做的事情。

是的，应该重新考虑开发人员可以完成的任务，但是框架应该已经存在，由那些知道为什么、何方和如何而不仅仅是什么的人创建的。这一切都是关于上下文的，为新来者提供参考，他们可以建立他们的理解。

Answer 3

开发人员或其他人应该编写(技术)文档吗？

这取决于：

• 我会用代码编写API引用。这意味着开发人员将与代码一起编写它，并且它可能是源代码的一部分(例如，在注释中)。将其放入代码中有一个额外的优点，即文档与代码一起更新。
• 至于入门材料，例如教程，最好是由有此经验的人编写。这可能是一个有教学经验和/或支持典型用户基础的人。

引用ReadTheDocs 文件编制原则的话：

“在文档过程中，从开发人员到最终用户，每个人都要参与进来。将文档集成到开发人员的标准工作流程中，并设法减少只从软件贡献者的一部分获取文档的筒仓。开发人员和工程师是最能访问按需信息的人，让他们将文档记录下来将有助于培养一种文档文化。”

其他几点：

• 无论如何，几个人的合作要比一个人好。如果您使用与软件相同的工具编写文档，那么您可能有一个检查文档的评审过程，以及它们作为拉请求/合并请求提交的过程。
• 决定文档的来源(例如Markdown、reStructuredText等)以及一条用于贡献的工具链。这将使几个人能够在文档上工作并保持最新。有些项目将docs源代码与代码保持在同一个repo中。示例(SaltStack:文档在https://docs.saltstack.com/上呈现，用reStructuredText (.rst)编写，可以通过"Edit me on GitHub“进行编辑，源代码在GitHup repo https://github.com/saltstack/salt/tree/master/doc中)
• 如果您有几个人在文档(无论如何)，最好是记下一些基本规则。这将防止不必要的讨论，并使文档更加一致。这通常是以风格指南的形式进行的。样式指南应该提到一些要点，如：
  • 拼写规则(例如标题大写)
  • 格式化规则(如果有的话)
  • 如何称呼读者，例如用“你.”来称呼他们
  • 用一种更正式的方式写
  • 等。