重新认识文档的重要性

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

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

一般项目能够大略的分为有规划、开发、收尾三个阶段。文档也在这三个阶段有着不同的效果。以我参加的物联网项目为例。

规划阶段

首要是在项目的规划阶段。这时的文档首要作为异步交流的东西，用来确认需求和流程。输出首要是一次序图，架构图为主，不会触及过多细节部分。这一阶段的文档改动会十分频繁。

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

假如有新增的服务或许是新引进的外部服务，比方云上的三方服务，这种时候就需求架构图和 POC 的规划了。这部份的文档首要用于内部技术方向的挑选。关于新的服务或许较杂乱的逻辑，没有书面化的文档首要难以理清思路，其次也没法作为技术选型的根据。毕竟在引进新技术或许做出较大的改变时，总是需求团队内部的交流和赞同的。

开发阶段

其次是在项目的开发阶段。这时的文档除了异步交流的东西外，还有供给运用的功用。这个阶段的输入依赖于规划阶段的文档，会增加具体的接口界说、数据结构界说，输出为接口文档、表结构文档等较为具体的部分，用来指导开发和与其他团队对接。与其他团队对接的部分要做的比较细心，而且这一阶段文档的细节更新会较多。

此刻或许会有担任开发的搭档参加进来，先前规划文档能够协助他们快速了解项目布景和自己担任的部分。假如规划文档没有做好，在这一阶段会花费较多的时刻在项目交流上，不只会影响接口文档的质量，甚至会产生影响进展的副效果。

服务端的接口文档，不只和开发有关更是需求供给给其他调用者参阅。因此关于接口参数的界说、传入和回来的数据格式最好能有具体的界说。关于触及到加解密算法的部分，最好能给出一个比如。而在这次的项目中，由于文档参数界说得不行严谨，花费了大量的时刻在一致参数上。尽管越是具体的文档，越是花费时刻，可是相比起后期由于了解误差花费在交流上的时刻还是值得的。

收尾阶段

最后是在项目的收尾阶段。这时的文档首要作为项目效果的总结和展现，一般作为 Sharing 和 KPI 的材料，一起也能够协助其他人了解项目的效果。作为后续保护和开发的根底。这个阶段的文档这一阶段的文档都是之前两阶段的文档经过修订后的文档，新的文档根本很少。

往往在这个阶段 QA 的搭档会介入项目。担任 API 测验的 QA 搭档就会参阅之前的接口文档编写测验用例一起也会根据规划文档了解完成上的细节部分。假如前两个文档编写质量不高的话，相同也会花费许多时刻在交流和解释上。

总结与考虑

文档其实和代码相同，相同有着生命周期，文档的内容也是需求更新和迭代的。一份高质量的文档，不只是自身专业性的体现，一起也能够下降交流的成本，对开发也有着协助。在习惯了公司规划 review 之后再开发的流程之后，整个 coding 的过程反而变得更轻松。曩昔 coding 到一半才会发现遗漏的次数也减少了。对我来说，写文档有利的面更多。

但文档的迭代和同步也的确是一件让人很烦恼的工作。一份文档和实践代码误差太大变成“死”文档是很可惜的事。目前公司的文档根本都是会集在 Confluence 上（Confluence 关于 markdown 的支撑并不是太好），但代码修改后文档的同步有依然会是一件费事的工作。短时刻的改动会让人厌烦，长时刻又容易遗漏从而形成文档与代码误差也是不愿意看到的。假如没有适宜文档编写东西或许载体，这个问题相信依然会困扰咱们。

本文由mdnice多平台发布