【软件工程之美 - 专栏笔记】16 | 怎样才能写好项目文档？

---

专栏信息

1. 专栏作者：宝玉

2. 专栏发布平台：极客时间

---

主要内容

---

总结

基本上大家都认同：“项目文档很重要”，然而我们在项目中总是短期高估文档的重要性，而长期低估文档的重要性。

结果就是口号喊的很响：要重视文档、要写好文档、要多写文档，然而随着项目的推进，总有比文档优先级更重要的任务，文档的优先级总是被有意无意推迟，导致项目的文档缺失、老旧、无人维护。

为什么程序员都不爱写文档呢？大致有下面这些原因：

1. 不知道怎么写
2. 太忙没时间写或者懒得写
3. 因为是敏捷开发，所以不用写文档？

一 为什么要写文档？

1. 帮助写文档的人理清楚思路
2. 便于未来的维护和交接
3. 便于团队更好的协作沟通

---

二 如何写好文档？

1. 从模仿开始
   模仿就是最好的写文档方式，尤其是现在网上可以参考的例子也很多，当你写文档不知道该如何下手的时候，不妨去找一个类似的文档，模仿着写试试。
2. 从小文档开始
   一开始写文档，内容不需要很多，可以从小的文档开始。就像前面我提到的，记一些笔记，不要在意格式，一两句话，一些截图，就是不错的笔记。
3. 从粗到细，迭代更新
   小时候写作文，老师给的最多的建议就是要列提纲，这个建议我小时候当耳边风没怎么听，后来要写项目文档的时候用起来反倒觉得非常实用。
4. 一些基本的画图的技巧
   有人说：“字不如表，表不如图，一图胜千言”。这个观点我非常认同，好的图能帮助你简单而直观地把问题说明清楚。

   • 线框图
     

   • 流程图
     

   • 时序图
     

   • 各种格式截图

     截图也是个非常简单直接的方式，把软件的 UI、交互设计的效果、数据趋势图、数据统计图等直接截图，必要的话配上一些箭头、文字，也可以很好的说明清楚问题。尤其是产品设计文档，经常用到。

---

三 一些关于文档的其他建议

有时候我也看到一些比较极端的情况，就是过于追求文档，项目中要花大量的时间写文档，而很多文档是形式化的，并没有太大意义，可能写完了不会用来讨论，也不会有人看。

敏捷宣言观点：文档很重要，但是工作的软件高于详尽的文档。这里面的平衡很重要。

四 其他摘抄

• 先写文档，就会抛开代码细节，去站在全局思考。
• 真正的障碍是没想清楚，在心中只有一些未成型的混乱的想法和概念，必须要努力把这些模糊的想法确定化和具体化，才能写出来。
• 换个角度来说，如果你连文档都写不出来，那又怎么能指望代码写得好呢？
• 写得越细则无用功越多，最后，你甚至会因为不想改文档而抵触不同的意见。
• 要画好流程图不难，重点是要理清楚逻辑关系，各个关键节点在不同条件下的走向。

---

总结

没时间写或者懒，不能成为不写文档的理由。对于重要的项目文档，就应该加入到日常的开发任务中，把写文档，摆在和设计、开发同等重要的位置。从某种角度来说，写不好文档，代码也很难写好。