2019-04-02领导常说“大脑是用来计算的，并不是用来记忆的。”
工作年头越多，越习惯将平时操作的过程整理成文档，分享给内部成员。
学的东西越多，记住的内容往往越少，将重复或可整理的内容写成文字，保存起来，使用的时候知道去哪里找就好。这也正是索引/缓存的妙处，利用大脑有限的Cache资源缓存常用的内容索引，将不常用的内容存盘，需要的时候再次加载。展开作者回复: 👍严重认同！
大脑是用来计算的，并不是用来记忆的，记忆一个索引就好了。 28
2019-04-02项目文档是整个项目的骨架，皮肉器官得自己一点一滴的增加，这样可以做到有迹可循，有法可依。开发人员写文档和写单元测试的心理是相似的，自己不愿写，但抱怨别人写得少。直到离开公司的那一天，总结起来就是业务代码写了一箩筐，还不能清晰的理清整个项目的业务结构，CURD的操作都赶上一万次理论了，但CURD怎么配合使用最高效、底层原理是什么，一概不知。
宝玉老师讲到不会写的问题，这确实是大多数底层开发人员的通病。有的时候很可气，比如邮件格式错误、文档有部分错别字、逻辑表达不清等等，都会让看的人很抓狂。在我看来，只要是合格的开发人员，都应该通过刻意练习来提高自己的软实力（英语水平、写作能力、语言表达能力等），不能只在乎自己硬实力多么多么精湛，让周围的人感受不到可以学习的空间。
部分开发人员到一定阶段会有很多的困惑，典型的就是努力的学习技术，却好像离技术越来越远，有一种恐惧和迷茫。其实，这是需要去克服的瓶颈期，输入（学习）的东西很多，输出（表达）的东西很少，学十只能知其一，学一百知十...，就会发现会的越来越少。相对于只进不出的一潭死水总是没有涓涓细流走得长远。
开发人员个人分享、写文档、写技术博客等等，这些可以伴随你走得更远的软实力都是必不可少的一门学问，甚至超过了技术本身，当然，这只是个人感想，也还处于摸索中。展开作者回复: 说的太对了，还有单元测试也是一样的，自己不愿意写还抱怨别人不写😄
后面几段总结的特别特别好👍
写文档比写作容易，都不需要刻意练习，稍微用点心就可以不错了。
输出就是要靠写，靠教，靠悟。就像学习攻略里面讲的：用器、学术、悟道、传道。 8
2019-04-03已经写好项目文档，但想更另一步优化文档，老师可以分享一下项目中需求规格说明书，概要设计，详细设计，代码规范文档，测试文档，部署文档等的优秀具体案例吗？特别想看看老师的，模仿学习？作者回复: 有些内部文档不方便分享。
我在文中附了一个开源项目的链接：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 6
2019-04-03谢谢😄……那不是在写文档上花费时间多，他们不一定会看，主要是为了以后方便维护和修改吗？作者回复: 磨刀不误砍柴工！
写有价值的文档、写单元测试，看起来要“浪费”一些时间，但是长远看，可以节约大量的时间。 3- 2019-04-02老师，你能简单说一下项目前-->项目中-->项目完成，一般都需要哪些文档呀，有没有示例或链接或搜索关键词？好让我们没有项目经验的，能见识一下
作者回复: 我大致列一下，可能有遗漏的：
项目立项：
原始需求文档
可行性分析报告
立项说明书
需求相关的：
原型设计文档
产品设计文档
系统设计相关的：
技术方案文档
详细设计文档
开发相关的：
代码规范文档
测试相关的：
测试用例
测试验收报告
运维相关的：
部署文档
故障报告
其实没有特别的标准的，还是根据各个阶段需要。原则上就是：
1. 这件事需要讨论需要评审，要有文档作为讨论的依据，以及记录讨论的结果。比如各种设计文档
2. 这件事要有规范，要有文档保证规范统一。比如各种规范文档
3. 这件事要记录下来，作为以后的一个参考。比如各种报告、环境配置、操作手册、API文档等 3 
2019-04-02文档的好坏也能看出一个程序员的水平～另外把文档也算做任务中一部分这个主意很赞，是不是也可以当作一个ticket？作者回复: 🤝英雄所见略同，我就是这么做的：文档、单元测试，都写成Ticket！
3
2019-04-09老师，需求分析之后是不是应该还有产品需求分析文档（PRD）和产品需求规格说明书？
一直不清楚项目中各个阶段应该具备的文档，所以很困惑。作者回复: 其实不必困惑这个问题，因为这本身没有特别的标准的。如果用瀑布模型开发，确实会有你说的文档，但如果是敏捷开发，可能会是另外的形式存在，例如每个小功能一个独立的用户故事，或者是独立的产品设计文档，只是讲清楚一个功能。
虽然形式不一样，但其目的都是一样：让大家可以讨论需求，可以理解需求。
之前我在另一条有回复过有哪些文档的问题：
1. 这件事需要讨论需要评审，要有文档作为讨论的依据，以及记录讨论的结果。比如各种设计文档
2. 这件事要有规范，要有文档保证规范统一。比如各种规范文档
3. 这件事要记录下来，作为以后的一个参考。比如各种报告、环境配置、操作手册、API文档等 2
2019-04-06我们组的文档处于中等水平，对外的接入文档很详细，对内的新人上手文档略有欠缺。看到老师说的那个到新团队后的习惯，我仿佛看到了知音，因为我最近就是这么做的。
看过一本书—数据文明，里面有个观点很好：对数据的记录的精细和全面的程度可以反映出文明的程度。放在软件工程的文档这件事上也很有指导意义—文档的清晰和全面程度反映了团队对项目的控制力。
我写文档重度依赖几个工具，推荐给大伙：语雀，印象笔记，xmind，omnigraffie，xnip截图，ppt作者回复: 谢谢分享！
我也是mindnode（有时候配合xmind），omnigraffie的重度用户。 2
2019-04-04对于详细设计文档的颗粒度一直有点疑问。
是写到类图或者时序图这种级别，说明不同类和方法之间的关系？
还是要细化到类似于伪代码级别，需要写操作哪个数据库表，和调用哪个api接口。这种写法比较费时间，但写出来后写代码就很容易了，基本上是按照开发语言的语法要求进行转换。我在项目中试着曾经推广过，但项目组成员认为工作量太大，基本是应付了事。
希望老师能根据自己的项目经验，看看写到哪个程度比较合适？作者回复: 我们2002年学软件工程的时候，推荐的写设计文档就是你说的这种细化到为伪代码级别，当时初衷是学习建筑行业，把写代码变成像搬砖砌墙一样，招一堆蓝翔培训出来就可以写代码。据说当年日本软件产业就是这样的。
实际上这些年下来，这种方法是不可行的（至少我没看到过成功案例），一个是设计文档写得太细，其实成本上已经跟写代码没差别了，不利于分工协作；另一个是写代码本身是一种创造性的劳动，当你把文档写到伪代码那么细，具体负责代码实现的没什么好发挥的空间了，都变成体力劳动了。
推荐的做法是写设计文档时不要太细，同时应该把具体模块的设计交给负责这个模块开发的人去做，指导他完成设计。这样既可以更好的分工协作，也可以让程序员有机会成长和充分发挥其主观能动性。 2- 2019-04-04谢谢老师哈，特别感谢🙏
作者回复: 不客气，有问题欢迎留言。
2 
2019-04-03项目组很少写文档，除非公司合规部要文档，就会冲冲的来一份，但是要回溯以前的内容，很费事。现在也没有人牵头弄这个事情，所以还是流程不规范，是以后的一个隐患作者回复: 可以尝试把一些关键的必要的文档，作为开发任务的一部分，分配时间，应该会好一点。
2
2019-04-02深有体会，没有文档的项目，对于项目的维护和交接代价太大了。 2
2019-04-02谢谢老师，上一期，按你提示，写了一个自动化静态代码检查工具，省了好多时间，现在学习机器学习也按项目来划分，将机器学习的每个知识点放到看板上。每完成一个就拿掉一个，感觉好很多。作者回复: 👍👍
很高兴看到你能学以致用，并且有效果！ 2
2019-09-18宝玉老师，您好，最近在帮忙项目组组员评审他们的模块设计文档。但是怎么帮他们评审却无从下手，不知道评审的标准是什么, 好的文档应该要具备哪些点，宝玉老师可否给些看法作者回复: 我觉得写好技术文档确实不容易，但也没有那么难，毕竟都是给自己内部看的，不要求特别好。
在评审技术文档或者你自己写技术文档，你可以从几个角度去思考：
1. 文档是否讲清楚了它的目的是什么？内容是否和目的匹配？
比如说你这个设计文档是要解决什么问题？设计的是哪个模块？
2. 文档是否解释了为什么要这么做？
比如说你这个模块设计文档，是否解释清楚了为什么要这样设计？这样设计的优缺点是什么？
3. 文档是否描述清楚了如何实现？
比如说作为模块设计文档，到底是如何设计的？有没有讲清楚整体的设计架构？
总结一下就是一个技术文档，要讲清楚：是什么（What）？为什么（Why）？怎么做（How）？这三个是最核心的要素。
这三个核心问题讲清楚了，然后就是多画图，内容简洁明了。 1 1
2019-09-121、就像测试代码一样，文档更新管理有什么好的建议，多久更新一次文档？2、如何理解代码就是最好的文档，代码可以替代文档吗？3、如何甄别无意义的文档？作者回复: 文档的更新通常是两种方式结合：
1. 即时更新，在内容发生变化时即时更新，或者发现文档不正确直接更新
2. 定期更新，根据团队的特点，定期例如每个月对关键文档进行审查和更新，至于周期设为多久，取决于你的团队能容忍多久不更新的文档
文档的更新要尽可能简单方便，不宜过于繁琐，当更新文档的成本过高，就会越发的没有更新文档的动力。
代码不能替代文档，好的代码可以帮助你理解代码。代码的问题在于很难直接通过代码看到全局架构，必须要配合有文档来从整体说明整体的架构。
为什么有人说代码就是最好的文档呢？并不是代码能替代文档，而是说阅读好的代码，能帮助你快速的理解代码的含义，不需要额外有文档说明；还有就是一些类似于繁琐的一步步的操作部署文档，完全可以用自动化脚本代码替代，从而不需要文档或只需要简单的文档。
没有价值的文档即无意义的文档！ 1
2019-04-16写文档是一个梳理过程!
说出来的东西逻辑性不足 错误不少，写文档的过程是一个优化、排错、提炼的过程，是思维由混乱变为条理的过程，不可或缺。
非常赞同文中的方法:由脑图而ppt,再到文档分节，然后补充内容。作者回复: 🤝是的，写文档从粗到细比较好些
1- 2019-04-09老师，我觉得一个项目中，文档应该分阶段、分角色；比如在项目开始时，项目经理应该写什么文档、产品经理应该写什么文档、开发应该写什么文档等等。但是对于这个我们公司做的很不规范、很模糊，一般都是项目经理兼职产品经理，甚至开发兼职项目、产品的角色。所以您这边能帮我们总结一下吗？
作者回复: 可以参考我给hua168留言的回复和给你另一条留言的回复。
1 
2019-04-03在开发过程中，比较习惯将一些重要的point归纳后罗列出来，因为有时很简单一句描述需要的代码并不少，过一段时间从代码中反推逻辑还是需要花些时间，不如直接写出来，或者的方法就是直接抽到一个方法中，让方法名来说明作者回复: 赞，谢谢补充分享👍
1
2019-04-02我们的项目文档基本上是以协议和流程为主，写这类文档的时候，实际上已经把项目的每一个细节都考虑清楚了，经过几次的review之后，后面的项目实现就是根据文档的内容再继续细化，一旦遇到不太清楚的地方，再回头翻阅文档，也很容易知道当初设计的时候是怎么一回事。
套用格式确实是一个比较好的方式，填空总是比直接写作文要简单的多，而一旦整个空都填满之后，再继续润色，细化那又会比一开始简单些。
写文档，记笔记等，用对工具还是很重要的。作者回复: 👍有价值的总结分享！
1
2019-04-02这节课很实用，为什么写文档?为什么写不好文档?为什么不想写文档?怎样写文档?这是程序员特别是高级程序员始终面对的问题作者回复: 是的，写文档没那么难，但是意义很大！
1