“文档”的确切构成是什么？

当我们说软件产品的“文档”时，其中包括什么，不应该包括什么？

例如，最近一个问题询问是否将注释视为文档？

但是在很多其他领域，这也是一个有效的问题，其中一些比其他领域更为明显：

• 手册（显然）
• 发行说明？
• 讲解
• 评论
• 还有其他吗？

画线在哪里。例如，如果“教程”是文档，是“视频教程”文档，还是其他？

通常，只有对软件中的某些内容进行实施，测试和记录后才能对其进行“完成”。因此，这个问题是，在考虑“完成”某些事情时，我们应该考虑哪些内容作为记录的一部分。

_{问题来自最近在我们的会议上的客户反馈，表明我们的文档需要更多的“样本”，而我们以前并没有像以前那样善于考虑。}

_{受众：使用我们的数据库，编程语言和相关工具（例如，所述数据库的管理员客户端）的软件开发人员}

文档的目的是描述和解释软件产品，因此您可以将文档定义为有助于该描述或解释的人工制品集。您可能不会考虑将相关操作作为文档的一部分：例如，为期一周的培训课程不是文档，而是课程资料；五分钟的白板聊天不是文档，而是白板的图像。

牢记目标（解释软件），当客户对说明满意时，完成文档：就像客户对软件满意时，完成软件一样。请记住，文档的客户与购买软件的客户并不总是相同的：支持人员，测试人员，销售人员和其他人员都需要对软件的功能及其工作方式有所了解。

这有助于了解文档中应包含的内容的界限。尽管我们接受可以包含视频或音频，但可以使用“阅读器”作为方便的速记方式：可以帮助读者获得有关软件的信息的任何内容都是他们可以使用的文档，而其他一切则不然。如果您的客户需要详细了解所有用例，则需要将其作为文档的一部分。您的开发人员可能需要源代码，有关版本控制存储库的信息以及构建说明：这是它们的文档，但是如上所述，它不属于客户文档的一部分。

我认为您从会议中的谈话中删除了错误的部分。现代软件开发方法论主张开发团队应与其客户​​（或充当客户代理的产品所有者）紧密合作。对于交付的所有工作，“完成”的定义是团队与客户之间协商确定的，并在开发软件时反复进行。

您遇到的问题是，您假设客户需要什么与他们希望您交付的东西之间存在脱节，因此最终您得到“嘿，所有样品都在哪里”的惊喜。

就什么是文档...好吧，这几乎是您列出的所有内容，也许还有您没有列出的其他内容。但是没有人能告诉您项目需要多少文档。每个项目都是不同的，这取决于您的团队，产品所有者和客户，以确定项目所需的文档级别和类型。

一些因素会起作用：

• 您是在开发软件v1.0并将其转移到其他项目，还是这个正在进行的长期项目？在后一种情况下，注释/设计文档变得更加重要。另一方面，如果您的客户是一家甜甜圈店，而您正在为他们编写一个网站，您将永远看不到...好吧，我想代码文档不错，但并不那么重要。
• 您是否正在开发用于控制医院中的心率监测器的移动游戏或软件。猜猜哪个将定义“完成”并包含更多文档？
• 您的客户是典型的最终用户还是其他开发人员？您有要公开的API / SDK吗？
• 您的客户的专业水平是多少？这会影响视频教程，书面材料以及某种交互式教程应用程序的选择
• 您的客户是否关心版本之间的变化。有的。大多数都不是。很少有人关心（或接近那个）法律。

文档是旨在阅读而无需修改的内容。

我认为使用基于目的的定义不会错...但前提是您正确定义了目的。

• ^{正确定义文档目的并不是一件容易的事。直截了当（如果您愿意的话，可以天真）的区别是，文档是供阅读的所有内容，而为了进行比较，代码是供计算机执行的所有内容。听起来不错，不是吗？但是，一旦您深入研究，结果确实很难看。
   
  事实是，好的代码要考虑到可读性以及执行的正确性，这使得“可读性”的区别在定义文档时毫无用处。您提到的样本
   
  非常清楚地表明了问题所在。客户通常希望这些文字写得清楚，正确执行。损害可读性或正确性会带来大量客户投诉。幼稚的区分并不能帮助您确定样本是代码还是文档。
   
  如果您想象使用开放源代码，那么使用朴素的区分会变得更加混乱。您下载，构建并运行它-您没有阅读，只是代码正确吗？等等，事情以某种方式出了问题，您进入了代码以阅读那里发生的事情……嘿，您没有读过-现在是这份文档吗？最后，您可以在源代码中找到错误并进行修复-现在，这实际上是代码，无论您多么认真地阅读以进行修复，它通常都不是文档。}

对于您将要提供的“样本”，“不修改”的区分可能非常重要。

您看，如果某些示例在不更改的情况下运行时失败，则在有文档的参考环境中，这是您的错误-文档中的错误，您必须接受并修复，这很好。

现在，如果修改的样本或环境存在问题，这不再是您的错-我的意思是文档中没有错误，因为docs不是用于修改的。无论您提供何种帮助，都属于支持类别，而不是错误修正。

回答“我如何...”问题的任何内容都是文档。

对于开发人员而言，这意味着需求规范（“我怎么知道该怎么写”），设计文档（“我如何满足我的需求”），可追溯性矩阵（“我如何知道我的设计满足了我所有的需求”），测试计划（“我怎么知道我的代码有效”），单元测试（“我如何知道满足X要求”），内联注释（“我如何确保下一个糟糕的schlub理解我为什么编写此代码”方式”，部署说明（“如何打包此产品以进行安装”）等。

对于用户而言，这意味着用户手册（“我如何使用该软件”），教程（“我如何使用此特定功能”），发行说明（“我如何知道已修复的错误 /新的错误功能已被修复）。已添加”）等