请大家多关注开发过程中的文档！

背景

很近没有记录自己的状况了，很多人都发来私信问我干嘛去了。我是去参加了一个由十几家公司配合的大项目，作为参与方，需要和各方进行协调讨论，加班为常态，每天都有小汇报，每周都有大总结。但是反思整个过程，依然觉得还是很操蛋。为什么这么说了？听我一一道来!

过程简述

该项目是一项有某大型单位主导，由10几家企业参与的较为大型的项目，这个大型，我觉的只是参与方较多，系统总体规模来说，我觉得只是算得上是中型吧！只是把A厂的产品和B厂的产品B进行整合。重新开发产品对于各个厂商来说都是又费工又费时的。所以都是在自己的产品上包装一个壳，使得暴露出来的接口可以很好的适应需求。

• 首先是有总指挥发不出整体的需求。
• 然后，各方根据自己产品的能力梳理出可以对接需求的接口。
• 最后需要相互对接的厂商，根据各自的文档，开发出一个壳子

整个过程就是这样，据我分析，关键步骤就是第二步，各个厂商根据总指挥的需求进行梳理。这个过程最后的产物就是最后的接口文档，在最后 的反思过程中我觉得整个流程还缺失了几步：

• 文档的评审及可行性分析
• 文档更新广播

为什么要又这几点呢？是因为在配合过程中，我发现虽然某些厂商参与了文档的制定，但是文档给出的字段并没有和实际代码中的完全一致？比如说bean在转json的时候，如果不做特殊的处理，可能会把字段又大写全部变为小写，并存在驼峰命名的习惯。但是文档不会根据程序进行改变。这就导致了文档与实际不对应的状况。

驴唇不对马嘴

文档评审的重要性

如果加一步评审步骤，可以及时的发现这些不必要产生的问题，我花在这个项目的时间20%的时间花在了因为文档字段名和实际字段不一致的问题上，如果遇到了这种问题，到底是哪一方进行修改？如果我这按照他们的文档改好了，其他的厂商会不会也出现这个问题！真是文档不规范，代码两行泪。

可行性分析的重要性

理想很美好，现实很骨感这句话用到文档审阅上，一点不差。理想上，通过这个A接口就能获取到数据，但是现实中会因为各种各样的原因让你取不到数据，或者效率低下。大家都知道，流的形式要比字符串的形式节省很多的时间。如果在交付文档的时候有各方技术代表做一个简单的验证，势必会节省很多不必要的时间浪费。如果一个接口的性能有问题，A厂商势必会调整接口，就会造成和他对接的B，C，D。。。等厂商也修改接口，这时间损失算起来也是不可估量的。

文档更新广播的重要性

领导在开会，工人在干活，这是很常见的现象。在开发过程经常会发现有些接口需要调整，A单位的人调整了接口interfaceA,告诉了A厂的领导，领导在开会过程中忘了广播，或者广播了其他厂商没有转播，再或者转播之后，干活的工人没有及时收到信息，不了解文档的最新状态。导致文档滞后，开发的接口不能对接上其他厂商。

如果有一个专门的文档广播系统。A厂商更新文档后广播到其他厂的领导，并且抄送到关键的干活人员。这样才不会有文档之后的出现。这次遇到一个问题就是A厂用的1.0.4的包，而我们收到的包确实1.0.0,一致排查不出哪里的问题，最后在完全复盘的时候才发现，包的版本不对。

总结

经过这多天的出差干活，真是让文档搞的头大。文档滞后，内容出错，版本不对，能遇到的都遇到了，真是服了！不过也的感谢这次出差机会，让我可以趁领导沟通的时间反思自己的发展方向。我还会把年初制定的读书计划继续完成好，如果有想加入的朋友，给我留言把，另外，还有出一个专栏，专门做机器学习的基础学习，毕竟基础不牢，地动山摇嘛！

在这里插入图片描述