重新认识文档的重要性

重新认识文档的重要性

2022 年有幸完整地参与了一个物联网项目，整个项目涉及APP、服务端、硬件三端交互。我参与服务端的设计与开发。同时受制于硬件，现有的对接逻辑也没发复用只能从零开始。在诸多 buff 的加持下，这个项目煎熬了我大半年。好在同组的小伙伴们比较给力，磕磕绊绊下也算完成了第一阶段的开发。

整个项目下来，最大的收获就是让我重新认识到了文档的重要性。特别是在跨团队的项目中有着不可或缺的作用。

一般项目可以粗略的分为有设计、开发、收尾三个阶段。文档也在这三个阶段有着不同的作用。以我参与的物联网项目为例。

设计阶段

首先是在项目的设计阶段。这时的文档主要作为异步沟通的工具，用来确认需求和流程。输出主要是一顺序图，架构图为主，不会涉及过多细节部分。这一阶段的文档改动会十分频繁。

因为这一次的项目相当于从零开始的全新设计，所以首先需要整理出主要的流程，比如设备的绑定、子设备的添加、设备解绑这些流程。这些流程已顺序图的形式，描绘三端交互的顺序和每一步的主要逻辑。这份文档除了面向自己组内，更主要的是让其他团队能理解主要流程设计，并且能给出相应意见。在跨团队的项目中，首先开会的时间有限，其次在会上讨论过大的议题则效率会很低。而事先通过文档进行沟通，在会上着重解决问题则会更有效率。

如果有新增的服务或者是新引入的外部服务，比如云上的三方服务，这种时候就需要架构图和 POC 的设计了。这部份的文档主要用于内部技术方向的选择。对于新的服务或者较复杂的逻辑，没有书面化的文档首先难以理清思路，其次也没法作为技术选型的依据。毕竟在引入新技术或者做出较大的变更时，总是需要团队内部的沟通和同意的。

开发阶段

其次是在项目的开发阶段。这时的文档除了异步沟通的工具外，还有提供使用的功能。这个阶段的输入依赖于设计阶段的文档，会添加详细的接口定义、数据结构定义，输出为接口文档、表结构文档等较为详细的部分，用来指导开发和与其他团队对接。与其他团队对接的部分要做的比较仔细，并且这一阶段文档的细节更新会较多。

此时可能会有负责开发的同事参与进来，先前设计文档可以帮助他们快速了解项目背景和自己负责的部分。如果设计文档没有做好，在这一阶段会花费较多的时间在项目沟通上，不仅会影响接口文档的质量，甚至会产生影响进度的副作用。

服务端的接口文档，不仅和开发有关更是需要提供给其他调用者参考。因此对于接口参数的定义、传入和返回的数据格式最好能有详细的定义。对于涉及到加解密算法的部分，最好能给出一个例子。而在这次的项目中，因为文档参数定义得不够严谨，花费了大量的时间在统一参数上。尽管越是详细的文档，越是花费时间，但是相比起后期因为理解偏差花费在沟通上的时间还是值得的。

收尾阶段

最后是在项目的收尾阶段。这时的文档主要作为项目成果的总结和展示，一般作为 Sharing 和 KPI 的资料，同时也可以帮助其他人了解项目的作用。作为后续维护和开发的基础。这个阶段的文档这一阶段的文档都是之前两阶段的文档经过修订后的文档，新的文档基本很少。

往往在这个阶段 QA 的同事会介入项目。负责 API 测试的 QA 同事就会参考之前的接口文档编写测试用例同时也会根据设计文档了解实现上的细节部分。如果前两个文档编写质量不高的话，同样也会花费很多时间在沟通和解释上。

总结与思考

文档其实和代码一样，同样有着生命周期，文档的内容也是需要更新和迭代的。一份高质量的文档，不仅是自身专业性的体现，同时也可以降低沟通的成本，对开发也有着帮助。在习惯了公司设计 review 之后再开发的流程之后，整个 coding 的过程反而变得更轻松。过去 coding 到一半才会发现遗漏的次数也减少了。对我来说，写文档有利的面更多。

但文档的迭代和同步也的确是一件让人很烦恼的事情。一份文档和实际代码偏差太大变成“死”文档是很可惜的事。目前公司的文档基本都是集中在 Confluence 上（Confluence 对于 markdown 的支持并不是太好），但代码修改后文档的同步有仍然会是一件麻烦的事情。短时间的改动会让人厌烦，长时间又容易遗漏从而造成文档与代码偏差也是不愿意看到的。如果没有合适文档编写工具或者载体，这个问题相信仍然会困扰我们。

本文由mdnice多平台发布