颓废青年，快出来挨打！
点击上方“Java极客技术”，选择“设为星标”
后台回复“java”，获取Java知识体系/面试必看资料
资料会持续更新，已更新第四次！
文章精品专栏
上午看了沈剑老师的两篇文章，内容主要关于技术文档。有感而发，下面从个人经历聊聊写文档这件事。
技术人需要写文档吗？
放在 1 年前问我这个问题，我肯定回答不需要。为什么？因为没有体会到写文档带来实质好处。需求代码都写不完，哪有空去写这玩意。
还记得刚参加工作的那两年，那时候不管接到什么需求，都会直接进行撸码，一边思考代码逻辑，一边实现功能。这个过程偶尔会发现一些问题，加班加点也能实现。所以在这一阵时间内，并不知道文档，所以也不会去想着写文档。
后来接到一个需求，需要接入第三方支付，搭建一个基础的支付系统。刚接到这个需求，想想需求实现也很简单吗。无非就是涉及几张表，然后调用第三方支付，完成一次支付。大致参考原有类似系统的实现方案，根据产品给出的需求文稿，没怎么经过仔细思考就开始实现功能，并且还盲目的给出一个工期。
后来实现过程中才发现各种问题，有的是因为项目需求不合理，当前系统根本无法完成这样的设计。所以这个时候需要跟产品讨论协调，如何折衷的改动，最后定下方案，然后删掉写到一半的代码，重新实现逻辑。
其次，原本以为有些功能其他项目组已经实现，直接调用即可。真正对接的时候才发现，他们提供接口根本不能当前需求。没办法只能让其他项目组的同学帮助实现，这就涉及到协调其他组同学开发。
另外这个项目还涉及到与客户端交互，所以需要提前给出交互接口的相关信息。客户端同学按照接口文档，进行接入调试。原以为给出完整的接口信息，可是在客户端同学接入的过程中，才发现有些页面需要新接口，有些接口交互逻辑不合理，这个过程又不得不去重新思考设计。
总之这个项目过程十分艰难，所幸靠着加班加点最终也将其完成。
回顾反思这个过程，我认为最根本的原因在于项目前期没有经过完整的详细系统设计，所有实现功完全按着产品需求流程走动。经历过这个项目之后，慢慢有了一些改变，会提前思考设计，才会去动手写代码。
去年加入现在的公司，公司流程规定，项目需求必须有详细的设计文档。当然，刚开始很反感这种规定，尤其还要将文档写在 word 上。
不过也没办法，慢慢开始接受了这种方式。刚开始以为写技术文档很简单，可是等到真正需要用文字输出的时候，才发现自己竟然写不明白。这个时候就不得不再去思考，去仔细理清逻辑。
今年在几个项目开始体验这种做法，想清楚了系统设计，然后写在文档上。由于前期已经将思路逻辑想明白了，后期代码实现过程照着实现就可以了。
所以现在问我技术人需要写文档吗？
我的回答是 需要。
引用沈剑老师文档的一段内容：
为什么要写设计文档？
对自己，让自己在动手写代码之前，帮助自己想得更清楚；
对项目，保证信息的一致性，保证项目的可控性，减少项目风险；
对团队，确保知识的沉淀与传承；
文档需要写些什么？
刚开始写技术文档时候，也只是大概写了一些交互流程，表结构设计之类。后面与测试交谈中才发现，他们测试会根据我们技术文档为基础，去设计测试案例。所以文档阅读者不仅仅是开发，还有可能是测试，甚至产品。
所以为了让文档能让大家都看明白，我们需要在文档中体现一下内容。
1. 需求描述。
阅读一份我们需要文档用途或者目的，所以需要一定需求描述。如果有对应需求文档，可以摘录需求文档描述即可。
2. 实现逻辑
我觉得最重要是这部分内容，从这部分内容我们可以了解到整个功能逻辑。在这部分功能，最好不要长篇大论，多使用程序图，时序图，ER 图去代替。这些图能很清晰代表逻辑。一些项目需要使用到业务规则，计算规则也可以写在这一部分。
3. 其他
一些项目难免会存在一些专有名词，可以在文档专门解析这些名词，这样后面描述中使用这些名词也不会让人疑惑。
总之，文档并不一定要按照某个具体格式去写，只要能写清楚，能让其他人理解，我觉得就足够了。
欢迎加入我们的知识星球，一起成长，交流经验。加入方式，长按下方二维码噢
最后，我想重复一句话：选择和一群优秀的人一起成长，你成长的速度绝对会不一样！
转发到朋友圈
让你身边的朋友看到好的文章，他会感谢你
明天见(｡･ω･｡)
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
