09 | 怎么才能写好项目文档

发布于 2021-11-25  666 次阅读


我以前看过一个投票,盘点程序员不喜欢的事,有两条和文档相关:

  • 不喜欢写文档;
  • 不喜欢项目文档太少。

看起来很矛盾,却很现实。基本上大家都认同:“项目文档很重要”,然而我们在项目中总是短期高估文档的重要性,而长期低估文档的重要性。

那么为什么程序员都不爱写文档呢?我总结了一下大致有下面这些原因。

  • 不知道怎么写
  • 太忙没时间写或者懒得写
  • 觉得敏捷开发不用写

为什么要写文档?

写文档,其实对个人、对项目、对团队,都是非常重要的事情。

  • 帮助写文档的人理清楚思路

写文档,可以让你在写代码之前,梳理清楚思路,想清楚整体结构,比如说有哪些工作是重点难点;哪些要依赖其他人,需要及早协商的;哪些是要考虑安全性的。

先写文档,就会抛开代码细节,去站在全局思考。写的时候,各个模块之间的依赖关系、各种可能的安全隐患、各种可能需要其他人配合的地方,就都冒出来了,必须要去查资料,去找人讨论,反复缜密的思考后最终写出来。

真正的障碍是没想清楚,在心中只有一些未成型的混乱的想法和概念,必须要努力把这些模糊的想法确定化和具体化,才能写出来。

  • 便于未来的维护和交接

“好记性不如烂笔头”,存在脑子里的内容是不可靠的,一个正常的项目组,如果需要长期维护,就需要一定的文档,把设计、操作流程、环境配置等内容记录下来,而不仅仅依赖于口口相传。

  • 便于团队更好的协作沟通

 

如何写好文档

1.从模仿开始

模仿就是最好的写文档方式,尤其是现在网上可以参考的例子也很多,当你写文档不知道该如何下手的时候,不妨去找一个类似的文档,模仿着写试试

2. 从小文档开始

3. 从粗到细,迭代更新

我写一个大一点的文档,都是从脑图开始的,先基于脑图,把基本结构梳理清楚。然后第二步就是写 PPT,PPT 有个好处就是不用太多文字,列个一二三,画几张图,就是个简单的文档,PPT 还有个好处就是可以用来给别人讲解,收集反馈。写完 PPT,也收集好了反馈,再写正式的文档。先按照脑图列的提纲把主要章节放上去,然后把 PPT 上的内容和画的图放到文档中,一篇文档的骨架就搭好了,剩下的就是对细节的补充了。

4. 善于画图

  • 线框图

线框图是最常用也最实用的一种图形,用简单的方框代替功能、模块、服务等,再用箭头表示关系或者数据流向,非常简单直接。

  • 流程图

流程图是软件项目文档中一种常用图形,可以方便的表示各种不同条件下的逻辑路径。要画好流程图不难,重点是要理清楚逻辑关系,各个关键节点在不同条件下的走向。

例:重置密码流程图。

  • 时序图

时序图也是软件项目所特有的一种图形,可以表示不同对象之间发送消息的时间顺序,尤其在涉及网络通信的文档中特别常用。画好时序图,关键是要列清楚所有涉及的对象或者服务,以及消息发送的先后顺序。

例:注销登录过程的时序图。

  • 各种格式截图

她喜欢所以就做咯