你好，哈布尔！ 我叫 Lesha，是阿尔法银行产品团队之一的系统分析师。 现在我正在为法人实体和个体企业家开发一个新的网上银行。
当您是一名分析师时，尤其是在这样的渠道中，如果没有文档并与之密切合作，您将一事无成。 文档总是会引发很多问题。 为什么没有描述 Web 应用程序？ 为什么规范指出了服务应该如何工作，但它根本不是那样工作的？ 为什么只有两个人（其中一个是编写它的人）能够理解该规范？
然而，由于显而易见的原因，文档不能被忽视。 为了让我们的生活更轻松，我们决定评估文档的质量。 我们究竟是如何做到这一点以及我们得出的结论低于切入点。
文档质量
为了不在文中重复几十遍“新网上银行”，我就写成NIB。 现在我们有十多个团队致力于为企业家和法人实体开发NIB。 此外，他们每个人要么从头开始为新服务或 Web 应用程序创建自己的文档，要么对当前文档进行更改。 通过这种方法，文档原则上可以达到高质量吗？
为了确定文档的质量，我们确定了三个主要特征。
- 它必须是完整的。 这听起来很像队长，但值得注意的是。 它应该详细描述所实施的解决方案的所有元素。
- 它必须是相关的。 也就是说，对应于解决方案本身的当前实现。
- 这应该是可以理解的。 以便使用它的人准确理解该解决方案是如何实施的。
总结一下——完整、最新且易于理解的文档。
Опрос
为了评估文档的质量，我们决定采访那些直接使用文档的人：NIB 分析师。 受访者被要求根据“从 10 到 1 的等级（完全不同意 - 完全同意）”方案评估 5 项陈述。
这些陈述反映了定性文件的特征以及调查编制者对 NIB 文件的意见。
- NIB 应用程序的文档是最新的并且与其实现完全一致。
- NIB 应用程序的实施有完整的文档记录。
- NIB 应用程序的文档仅用于功能支持。
- NIB 应用程序的文档在提交功能支持时是最新的。
- NIB 应用程序开发人员使用文档来了解他们需要实现的内容。
- NIB 应用程序有足够的文档来了解它们是如何实现的。
- 如果 NIB 项目（由我的团队）最终确定，我会立即更新它们。
- NIB 应用程序开发人员查看文档。
- 我对如何为NIB项目准备文档有了清晰的了解。
- 我了解何时为 NIB 项目编写/更新文档。
显然，简单地回答“从 1 到 5”可能不会透露必要的细节，因此人们可以对每个项目发表评论。
我们通过公司 Slack 完成了这一切 - 我们只是向系统分析师发出了参与调查的邀请。 共有 15 名分析师（9 名来自莫斯科，6 名来自圣彼得堡）。 调查完成后，我们为这 10 个陈述中的每一个给出了平均分，然后将其标准化。
事实证明那是什么。
调查显示，尽管分析师倾向于认为 NIB 应用程序的实施已得到完整记录，但他们并没有给出明确的一致意见 (0.2)。 作为一个具体的例子，他们指出现有解决方案中的许多数据库和队列并未包含在文档中。 开发人员能够告诉分析师并非所有内容都已记录在案。 但开发人员审查文档的论点也没有得到明确的支持（0.33）。 也就是说，所实施的解决方案描述不完整的风险仍然存在。
相关性更容易 - 尽管再次没有明确的一致意见（0,13），但分析师仍然倾向于认为文档具有相关性。 这些评论让我们了解到，相关问题往往出现在前面，而不是中间。 然而，他们没有给我们写任何有关支持的信息。
至于分析师自己是否理解何时需要编写和更新文档，协议更加统一（1,33），包括其设计（1.07）。 这里指出的一个不便之处在于缺乏维护文档的统一规则。 因此，为了不开启“谁进森林，谁得柴”的模式，他们必须基于现有文档的示例来工作。 因此，一个有用的愿望是创建文档管理标准并为其部分开发模板。
NIB 应用程序的文档在提交功能支持 (0.73) 时是最新的。 这是可以理解的，因为提交项目以获得功能支持的标准之一是最新的文档。 尽管有时仍然存在问题，但理解实现（0.67）也足够了。
但受访者不同意（非常一致）的是，NIB 应用程序的文档原则上只需要功能支持（-1.53）。 分析师最常被提及为文档的消费者。 团队的其他成员（开发人员）——频率要低得多。 此外，分析师认为，开发人员不会使用文档来理解他们需要实现的内容，尽管并不一致（-0.06）。 顺便说一下，在代码开发和文档编写并行进行的情况下，这也是预期的。
底线是什么？为什么我们需要这些数字？
为提高文档质量，我们决定采取以下措施：
- 要求开发商审查书面文件。
- 如果可能的话，及时更新文档，前面先更新。
- 创建并采用记录 NIB 项目的标准，以便每个人都可以快速了解应描述哪些系统元素以及如何准确描述。 好吧，开发合适的模板。
所有这些都有助于将文档的质量提高到一个新的水平。
至少我希望如此。
来源： habr.com