哈Ha！ 我叫Lesha，我是Alfa-Bank产品团队之一的系统分析师。 现在，我正在为法律实体和个人企业家开发新的互联网银行。
而且，当您是分析师时，尤其是在这种渠道中，没有文档并且很难使用它-无处可去。 而文档总是引起很多问题。 为什么未描述Web应用程序？ 为什么规范说明了服务应如何工作，却根本不起作用？ 为什么只有两个人能理解该规范，而其中一个是编写该规范的呢？
但是，由于明显的原因，不能忽略文档。 为了简化我们的生活，我们决定评估文档的质量。 我们是如何做到的以及得出什么结论-在削减的情况下。
文件品质
为了不重复“ New Internet Bank”文本数十次，我将写NIB。 现在，我们有十几个团队致力于为企业家和法律实体开发NIB。 此外，它们中的每一个要么从头开始为新服务或Web应用程序创建自己的文档，要么对当前服务或Web应用程序进行更改。 通过这种方法，原则上文档可以高质量吗？
为了确定文档的质量，我们确定了三个主要特征。
- 它必须完整。 听起来很漂亮，但要注意。 它应该详细描述已实现解决方案的所有元素。
- 它应该是相关的。 也就是说，对应于解决方案本身的当前实现。
- 应该清楚。 使使用它的人员了解解决方案的实施方式。
总结-完整，相关且易于理解的文档。
投票
为了评估文档的质量，我们决定采访直接与之合作的人员：NIB分析师。 要求受访者根据“以1到5的等级（完全不同意-完全同意）”的方案对10条陈述进行评分。
这些指控反映了质量文件的特点以及调查编制者对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项目的标准，以便每个人都可以快速了解系统的哪些元素以及如何对其进行描述。 好了，开发合适的模板。
所有这些都应有助于将文档质量提高到一个新水平。
至少我希望如此。