16 | 怎样才能写好项目文档？
该思维导图由 AI 生成，仅供参考
为什么要写文档？
荧光笔
直线
曲线- 深入了解
- 翻译
- 解释
- 总结
程序员不喜欢写项目文档，但文档对个人、项目和团队都非常重要。写文档可以帮助理清思路，避免陷入技术细节，提前发现问题和隐患。文档也有利于未来的维护和交接，记录设计、操作流程和环境配置，避免口口相传的不可靠情况。此外，文档也有助于团队协作沟通，成为团队成员之间良好的沟通工具。因此，尽管程序员可能觉得写文档麻烦，但文档对于项目的成功和团队的协作至关重要。 文章提出了如何写好软件项目文档的建议。首先，作者强调了正确的文档写作认识，强调内容表达的重要性。其次，建议从模仿开始，通过参考类似文档进行模仿学习。接着，建议从小文档开始，逐步积累并完善文档内容。作者还提出了从粗到细、迭代更新的写作方式，并介绍了一些基本的画图技巧。此外，文章还给出了一些关于文档的其他建议，如平衡文档与代码的关系、使用Markdown格式、选择在线文档工具等。 总的来说，文章提供了丰富的写作建议和技巧，对于需要提升文档写作能力的程序员和团队成员具有很高的参考价值。
《软件工程之美》，新⼈⾸单¥59
全部留言(30)
- 最新
- 精选
青石领导常说“大脑是用来计算的，并不是用来记忆的。” 工作年头越多，越习惯将平时操作的过程整理成文档，分享给内部成员。 学的东西越多，记住的内容往往越少，将重复或可整理的内容写成文字，保存起来，使用的时候知道去哪里找就好。这也正是索引/缓存的妙处，利用大脑有限的Cache资源缓存常用的内容索引，将不常用的内容存盘，需要的时候再次加载。作者回复: 👍严重认同！ 大脑是用来计算的，并不是用来记忆的，记忆一个索引就好了。
2019-04-02358
Bo已经写好项目文档，但想更另一步优化文档，老师可以分享一下项目中需求规格说明书，概要设计，详细设计，代码规范文档，测试文档，部署文档等的优秀具体案例吗？特别想看看老师的，模仿学习？作者回复: 有些内部文档不方便分享。 我在文中附了一个开源项目的链接：https://video-react.js.org/ 这个是一个组件使用文档 其实类似的有很多开源项目的文档都写得很好。比如： Vue: https://cn.vuejs.org/v2/guide/ Redux: https://redux.js.org/ 还有可以网上搜索一些，例如： 产品需求文档模板：https://www.jianshu.com/p/e89e97858be1 微服务：从设计到部署： https://docshome.gitbooks.io/microservices/content/2-using-an-api-gateway.html
2019-04-0321
易林林项目文档是整个项目的骨架，皮肉器官得自己一点一滴的增加，这样可以做到有迹可循，有法可依。开发人员写文档和写单元测试的心理是相似的，自己不愿写，但抱怨别人写得少。直到离开公司的那一天，总结起来就是业务代码写了一箩筐，还不能清晰的理清整个项目的业务结构，CURD的操作都赶上一万次理论了，但CURD怎么配合使用最高效、底层原理是什么，一概不知。 宝玉老师讲到不会写的问题，这确实是大多数底层开发人员的通病。有的时候很可气，比如邮件格式错误、文档有部分错别字、逻辑表达不清等等，都会让看的人很抓狂。在我看来，只要是合格的开发人员，都应该通过刻意练习来提高自己的软实力（英语水平、写作能力、语言表达能力等），不能只在乎自己硬实力多么多么精湛，让周围的人感受不到可以学习的空间。 部分开发人员到一定阶段会有很多的困惑，典型的就是努力的学习技术，却好像离技术越来越远，有一种恐惧和迷茫。其实，这是需要去克服的瓶颈期，输入（学习）的东西很多，输出（表达）的东西很少，学十只能知其一，学一百知十...，就会发现会的越来越少。相对于只进不出的一潭死水总是没有涓涓细流走得长远。 开发人员个人分享、写文档、写技术博客等等，这些可以伴随你走得更远的软实力都是必不可少的一门学问，甚至超过了技术本身，当然，这只是个人感想，也还处于摸索中。作者回复: 说的太对了，还有单元测试也是一样的，自己不愿意写还抱怨别人不写😄 后面几段总结的特别特别好👍 写文档比写作容易，都不需要刻意练习，稍微用点心就可以不错了。 输出就是要靠写，靠教，靠悟。就像学习攻略里面讲的：用器、学术、悟道、传道。
2019-04-0220
hua168老师，你能简单说一下项目前-->项目中-->项目完成，一般都需要哪些文档呀，有没有示例或链接或搜索关键词？好让我们没有项目经验的，能见识一下作者回复: 我大致列一下，可能有遗漏的： 项目立项： 原始需求文档 可行性分析报告 立项说明书 需求相关的： 原型设计文档 产品设计文档 系统设计相关的： 技术方案文档 详细设计文档 开发相关的： 代码规范文档 测试相关的： 测试用例 测试验收报告 运维相关的： 部署文档 故障报告 其实没有特别的标准的，还是根据各个阶段需要。原则上就是： 1. 这件事需要讨论需要评审，要有文档作为讨论的依据，以及记录讨论的结果。比如各种设计文档 2. 这件事要有规范，要有文档保证规范统一。比如各种规范文档 3. 这件事要记录下来，作为以后的一个参考。比如各种报告、环境配置、操作手册、API文档等
2019-04-0215
dancer文档的好坏也能看出一个程序员的水平～另外把文档也算做任务中一部分这个主意很赞，是不是也可以当作一个ticket？作者回复: 🤝英雄所见略同，我就是这么做的：文档、单元测试，都写成Ticket！
2019-04-026
邢爱明对于详细设计文档的颗粒度一直有点疑问。 是写到类图或者时序图这种级别，说明不同类和方法之间的关系？ 还是要细化到类似于伪代码级别，需要写操作哪个数据库表，和调用哪个api接口。这种写法比较费时间，但写出来后写代码就很容易了，基本上是按照开发语言的语法要求进行转换。我在项目中试着曾经推广过，但项目组成员认为工作量太大，基本是应付了事。 希望老师能根据自己的项目经验，看看写到哪个程度比较合适？作者回复: 我们2002年学软件工程的时候，推荐的写设计文档就是你说的这种细化到为伪代码级别，当时初衷是学习建筑行业，把写代码变成像搬砖砌墙一样，招一堆蓝翔培训出来就可以写代码。据说当年日本软件产业就是这样的。 实际上这些年下来，这种方法是不可行的（至少我没看到过成功案例），一个是设计文档写得太细，其实成本上已经跟写代码没差别了，不利于分工协作；另一个是写代码本身是一种创造性的劳动，当你把文档写到伪代码那么细，具体负责代码实现的没什么好发挥的空间了，都变成体力劳动了。 推荐的做法是写设计文档时不要太细，同时应该把具体模块的设计交给负责这个模块开发的人去做，指导他完成设计。这样既可以更好的分工协作，也可以让程序员有机会成长和充分发挥其主观能动性。
2019-04-0425- hua168谢谢😄……那不是在写文档上花费时间多，他们不一定会看，主要是为了以后方便维护和修改吗？
作者回复: 磨刀不误砍柴工！ 写有价值的文档、写单元测试，看起来要“浪费”一些时间，但是长远看，可以节约大量的时间。
2019-04-035 
bearlu谢谢老师，上一期，按你提示，写了一个自动化静态代码检查工具，省了好多时间，现在学习机器学习也按项目来划分，将机器学习的每个知识点放到看板上。每完成一个就拿掉一个，感觉好很多。作者回复: 👍👍 很高兴看到你能学以致用，并且有效果！
2019-04-024
LiYanbin宝玉老师，您好，最近在帮忙项目组组员评审他们的模块设计文档。但是怎么帮他们评审却无从下手，不知道评审的标准是什么, 好的文档应该要具备哪些点，宝玉老师可否给些看法作者回复: 我觉得写好技术文档确实不容易，但也没有那么难，毕竟都是给自己内部看的，不要求特别好。 在评审技术文档或者你自己写技术文档，你可以从几个角度去思考： 1. 文档是否讲清楚了它的目的是什么？内容是否和目的匹配？ 比如说你这个设计文档是要解决什么问题？设计的是哪个模块？ 2. 文档是否解释了为什么要这么做？ 比如说你这个模块设计文档，是否解释清楚了为什么要这样设计？这样设计的优缺点是什么？ 3. 文档是否描述清楚了如何实现？ 比如说作为模块设计文档，到底是如何设计的？有没有讲清楚整体的设计架构？ 总结一下就是一个技术文档，要讲清楚：是什么（What）？为什么（Why）？怎么做（How）？这三个是最核心的要素。 这三个核心问题讲清楚了，然后就是多画图，内容简洁明了。
2019-09-1822
阿G聊产品老师，需求分析之后是不是应该还有产品需求分析文档（PRD）和产品需求规格说明书？ 一直不清楚项目中各个阶段应该具备的文档，所以很困惑。作者回复: 其实不必困惑这个问题，因为这本身没有特别的标准的。如果用瀑布模型开发，确实会有你说的文档，但如果是敏捷开发，可能会是另外的形式存在，例如每个小功能一个独立的用户故事，或者是独立的产品设计文档，只是讲清楚一个功能。 虽然形式不一样，但其目的都是一样：让大家可以讨论需求，可以理解需求。 之前我在另一条有回复过有哪些文档的问题： 1. 这件事需要讨论需要评审，要有文档作为讨论的依据，以及记录讨论的结果。比如各种设计文档 2. 这件事要有规范，要有文档保证规范统一。比如各种规范文档 3. 这件事要记录下来，作为以后的一个参考。比如各种报告、环境配置、操作手册、API文档等
2019-04-092
