软件工程之美
宝玉
Groupon资深工程师,微软最有价值专家
立即订阅
6741 人已学习
课程目录
已完结 54 讲
0/4登录后,你可以任选4讲全文学习。
课前必读 (3讲)
开篇词 | 你为什么应该学好软件工程?
免费
特别放送 | 从软件工程的角度解读任正非的新年公开信
学习攻略 | 怎样学好软件工程?
基础理论 (9讲)
01 | 到底应该怎样理解软件工程?
02 | 工程思维:把每件事都当作一个项目来推进
03 | 瀑布模型:像工厂流水线一样把软件开发分层化
04 | 瀑布模型之外,还有哪些开发模型?
05 | 敏捷开发到底是想解决什么问题?
06 | 大厂都在用哪些敏捷方法?(上)
07 | 大厂都在用哪些敏捷方法?(下)
08 | 怎样平衡软件质量与时间成本范围的关系?
“一问一答”第1期 | 30个软件开发常见问题解决策略
项目规划篇 (8讲)
09 | 为什么软件工程项目普遍不重视可行性分析?
10 | 如果你想技术转管理,先来试试管好一个项目
11 | 项目计划:代码未动,计划先行
12 | 流程和规范:红绿灯不是约束,而是用来提高效率
13 | 白天开会,加班写代码的节奏怎么破?
14 | 项目管理工具:一切管理问题,都应思考能否通过工具解决
15 | 风险管理:不能盲目乐观,凡事都应该有B计划
16 | 怎样才能写好项目文档?
需求分析篇 (5讲)
17 | 需求分析到底要分析什么?怎么分析?
18 | 原型设计:如何用最小的代价完成产品特性?
19 | 作为程序员,你应该有产品意识
20 | 如何应对让人头疼的需求变更问题?
“一问一答”第2期 | 30个软件开发常见问题解决策略
系统设计篇 (4讲)
21 | 架构设计:普通程序员也能实现复杂系统?
22 | 如何为项目做好技术选型?
23 | 架构师:不想当架构师的程序员不是好程序员
24 | 技术债务:是继续修修补补凑合着用,还是推翻重来?
开发编码篇 (7讲)
25 | 有哪些方法可以提高开发效率?
26 | 持续交付:如何做到随时发布新版本到生产环境?
27 | 软件工程师的核心竞争力是什么?(上)
28 | 软件工程师的核心竞争力是什么?(下)
29 | 自动化测试:如何把Bug杀死在摇篮里?
30 | 用好源代码管理工具,让你的协作更高效
“一问一答”第3期 | 18个软件开发常见问题解决策略
软件测试篇 (4讲)
31 | 软件测试要为产品质量负责吗?
32 | 软件测试:什么样的公司需要专职测试?
33 | 测试工具:为什么不应该通过QQ/微信/邮件报Bug?
34 | 账号密码泄漏成灾,应该怎样预防?
运行维护篇 (6讲)
35 | 版本发布:软件上线只是新的开始
36 | DevOps工程师到底要做什么事情?
37 | 遇到线上故障,你和高手的差距在哪里?
38 | 日志管理:如何借助工具快速发现和定位产品问题 ?
39 | 项目总结:做好项目复盘,把经验变成能力
“一问一答”第4期 | 14个软件开发常见问题解决策略
经典案例解析篇 (7讲)
40 | 最佳实践:小团队如何应用软件工程?
41 | 为什么程序员的业余项目大多都死了?
42 | 反面案例:盘点那些失败的软件项目
43 | 以VS Code为例,看大型开源项目是如何应用软件工程的?
44 | 微软、谷歌、阿里巴巴等大厂是怎样应用软件工程的?
45 | 从软件工程的角度看微服务、云计算、人工智能这些新技术
“一问一答”第5期(内含彩蛋) | 22个软件开发常见问题解决策略
结束语 (1讲)
结束语 | 万事皆项目,软件工程无处不在
软件工程之美
登录|注册

16 | 怎样才能写好项目文档?

宝玉 2019-04-02
你好,我是宝玉,我今天分享的主题是:为什么你不爱写项目文档?以及怎样才能写好项目文档?
我以前看过一个投票,盘点程序员不喜欢的事,有两条和文档相关:
不喜欢写文档;
不喜欢项目文档太少。
看起来很矛盾,却很现实。基本上大家都认同:“项目文档很重要”,然而我们在项目中总是短期高估文档的重要性,而长期低估文档的重要性。
结果就是口号喊的很响:要重视文档、要写好文档、要多写文档,然而随着项目的推进,总有比文档优先级更重要的任务,文档的优先级总是被有意无意推迟,导致项目的文档缺失、老旧、无人维护。
那么为什么程序员都不爱写文档呢?我总结了一下大概有下面这些原因。
不知道怎么写
不知道怎么写文档的应该占很大一部分比例。
太忙没时间写或者懒得写
程序员确实很忙,但总有不那么忙的时候,却也很少见有人利用这时间去写文档。包括我自己也这样,有时候没那么忙的时候,宁可去想想怎么重构下代码,却很少会愿意去写文档,主要还是太懒。
敏捷开发所以不用写文档?
对于这个问题,我其实反驳过多次,敏捷宣言最后一句话明确指出:“尽管右项有其价值,我们更重视左项的价值。”也就是说敏捷从来没有否认文档的价值,只是更重视“工作的软件”罢了。

为什么要写文档?

取消
完成
0/1000字
划线
笔记
复制
© 版权归极客邦科技所有,未经许可不得传播售卖。 页面已增加防盗追踪,如有侵权极客邦将依法追究其法律责任。
该试读文章来自付费专栏《软件工程之美》,如需阅读全部文章,
请订阅文章所属专栏。
立即订阅
登录 后留言

精选留言(23)

  • 青石
    领导常说“大脑是用来计算的,并不是用来记忆的。”

    工作年头越多,越习惯将平时操作的过程整理成文档,分享给内部成员。

    学的东西越多,记住的内容往往越少,将重复或可整理的内容写成文字,保存起来,使用的时候知道去哪里找就好。这也正是索引/缓存的妙处,利用大脑有限的Cache资源缓存常用的内容索引,将不常用的内容存盘,需要的时候再次加载。

    作者回复: 👍严重认同!

    大脑是用来计算的,并不是用来记忆的,记忆一个索引就好了。

    2019-04-02
    25
  • kirogiyi
    项目文档是整个项目的骨架,皮肉器官得自己一点一滴的增加,这样可以做到有迹可循,有法可依。开发人员写文档和写单元测试的心理是相似的,自己不愿写,但抱怨别人写得少。直到离开公司的那一天,总结起来就是业务代码写了一箩筐,还不能清晰的理清整个项目的业务结构,CURD的操作都赶上一万次理论了,但CURD怎么配合使用最高效、底层原理是什么,一概不知。

    宝玉老师讲到不会写的问题,这确实是大多数底层开发人员的通病。有的时候很可气,比如邮件格式错误、文档有部分错别字、逻辑表达不清等等,都会让看的人很抓狂。在我看来,只要是合格的开发人员,都应该通过刻意练习来提高自己的软实力(英语水平、写作能力、语言表达能力等),不能只在乎自己硬实力多么多么精湛,让周围的人感受不到可以学习的空间。

    部分开发人员到一定阶段会有很多的困惑,典型的就是努力的学习技术,却好像离技术越来越远,有一种恐惧和迷茫。其实,这是需要去克服的瓶颈期,输入(学习)的东西很多,输出(表达)的东西很少,学十只能知其一,学一百知十...,就会发现会的越来越少。相对于只进不出的一潭死水总是没有涓涓细流走得长远。

    开发人员个人分享、写文档、写技术博客等等,这些可以伴随你走得更远的软实力都是必不可少的一门学问,甚至超过了技术本身,当然,这只是个人感想,也还处于摸索中。

    作者回复: 说的太对了,还有单元测试也是一样的,自己不愿意写还抱怨别人不写😄

    后面几段总结的特别特别好👍

    写文档比写作容易,都不需要刻意练习,稍微用点心就可以不错了。

    输出就是要靠写,靠教,靠悟。就像学习攻略里面讲的:用器、学术、悟道、传道。

    2019-04-02
    8
  • 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-03
    6
  • hua168
    谢谢😄……那不是在写文档上花费时间多,他们不一定会看,主要是为了以后方便维护和修改吗?

    作者回复: 磨刀不误砍柴工!
    写有价值的文档、写单元测试,看起来要“浪费”一些时间,但是长远看,可以节约大量的时间。

    2019-04-03
    3
  • hua168
    老师,你能简单说一下项目前-->项目中-->项目完成,一般都需要哪些文档呀,有没有示例或链接或搜索关键词?好让我们没有项目经验的,能见识一下

    作者回复: 我大致列一下,可能有遗漏的:
    项目立项:

    原始需求文档
    可行性分析报告
    立项说明书

    需求相关的:
    原型设计文档
    产品设计文档

    系统设计相关的:
    技术方案文档
    详细设计文档

    开发相关的:
    代码规范文档

    测试相关的:
    测试用例
    测试验收报告

    运维相关的:
    部署文档
    故障报告

    其实没有特别的标准的,还是根据各个阶段需要。原则上就是:
    1. 这件事需要讨论需要评审,要有文档作为讨论的依据,以及记录讨论的结果。比如各种设计文档
    2. 这件事要有规范,要有文档保证规范统一。比如各种规范文档
    3. 这件事要记录下来,作为以后的一个参考。比如各种报告、环境配置、操作手册、API文档等

    2019-04-02
    3
  • dancer
    文档的好坏也能看出一个程序员的水平~另外把文档也算做任务中一部分这个主意很赞,是不是也可以当作一个ticket?

    作者回复: 🤝英雄所见略同,我就是这么做的:文档、单元测试,都写成Ticket!

    2019-04-02
    3
  • Kevin
    宝玉老师,您好,最近在帮忙项目组组员评审他们的模块设计文档。但是怎么帮他们评审却无从下手,不知道评审的标准是什么, 好的文档应该要具备哪些点,宝玉老师可否给些看法

    作者回复: 我觉得写好技术文档确实不容易,但也没有那么难,毕竟都是给自己内部看的,不要求特别好。

    在评审技术文档或者你自己写技术文档,你可以从几个角度去思考:

    1. 文档是否讲清楚了它的目的是什么?内容是否和目的匹配?
    比如说你这个设计文档是要解决什么问题?设计的是哪个模块?

    2. 文档是否解释了为什么要这么做?
    比如说你这个模块设计文档,是否解释清楚了为什么要这样设计?这样设计的优缺点是什么?

    3. 文档是否描述清楚了如何实现?
    比如说作为模块设计文档,到底是如何设计的?有没有讲清楚整体的设计架构?

    总结一下就是一个技术文档,要讲清楚:是什么(What)?为什么(Why)?怎么做(How)?这三个是最核心的要素。

    这三个核心问题讲清楚了,然后就是多画图,内容简洁明了。

    2019-09-18
    2
  • 晓伟呢。☀
    老师,需求分析之后是不是应该还有产品需求分析文档(PRD)和产品需求规格说明书?
    一直不清楚项目中各个阶段应该具备的文档,所以很困惑。

    作者回复: 其实不必困惑这个问题,因为这本身没有特别的标准的。如果用瀑布模型开发,确实会有你说的文档,但如果是敏捷开发,可能会是另外的形式存在,例如每个小功能一个独立的用户故事,或者是独立的产品设计文档,只是讲清楚一个功能。

    虽然形式不一样,但其目的都是一样:让大家可以讨论需求,可以理解需求。

    之前我在另一条有回复过有哪些文档的问题:
    1. 这件事需要讨论需要评审,要有文档作为讨论的依据,以及记录讨论的结果。比如各种设计文档
    2. 这件事要有规范,要有文档保证规范统一。比如各种规范文档
    3. 这件事要记录下来,作为以后的一个参考。比如各种报告、环境配置、操作手册、API文档等

    2019-04-09
    2
  • javaadu
    我们组的文档处于中等水平,对外的接入文档很详细,对内的新人上手文档略有欠缺。看到老师说的那个到新团队后的习惯,我仿佛看到了知音,因为我最近就是这么做的。

    看过一本书—数据文明,里面有个观点很好:对数据的记录的精细和全面的程度可以反映出文明的程度。放在软件工程的文档这件事上也很有指导意义—文档的清晰和全面程度反映了团队对项目的控制力。

    我写文档重度依赖几个工具,推荐给大伙:语雀,印象笔记,xmind,omnigraffie,xnip截图,ppt

    作者回复: 谢谢分享!
    我也是mindnode(有时候配合xmind),omnigraffie的重度用户。

    2019-04-06
    2
  • 邢爱明
    对于详细设计文档的颗粒度一直有点疑问。
    是写到类图或者时序图这种级别,说明不同类和方法之间的关系?
    还是要细化到类似于伪代码级别,需要写操作哪个数据库表,和调用哪个api接口。这种写法比较费时间,但写出来后写代码就很容易了,基本上是按照开发语言的语法要求进行转换。我在项目中试着曾经推广过,但项目组成员认为工作量太大,基本是应付了事。
    希望老师能根据自己的项目经验,看看写到哪个程度比较合适?

    作者回复: 我们2002年学软件工程的时候,推荐的写设计文档就是你说的这种细化到为伪代码级别,当时初衷是学习建筑行业,把写代码变成像搬砖砌墙一样,招一堆蓝翔培训出来就可以写代码。据说当年日本软件产业就是这样的。

    实际上这些年下来,这种方法是不可行的(至少我没看到过成功案例),一个是设计文档写得太细,其实成本上已经跟写代码没差别了,不利于分工协作;另一个是写代码本身是一种创造性的劳动,当你把文档写到伪代码那么细,具体负责代码实现的没什么好发挥的空间了,都变成体力劳动了。

    推荐的做法是写设计文档时不要太细,同时应该把具体模块的设计交给负责这个模块开发的人去做,指导他完成设计。这样既可以更好的分工协作,也可以让程序员有机会成长和充分发挥其主观能动性。

    2019-04-04
    2
  • Bo
    谢谢老师哈,特别感谢🙏

    作者回复: 不客气,有问题欢迎留言。

    2019-04-04
    2
  • williamcai
    项目组很少写文档,除非公司合规部要文档,就会冲冲的来一份,但是要回溯以前的内容,很费事。现在也没有人牵头弄这个事情,所以还是流程不规范,是以后的一个隐患

    作者回复: 可以尝试把一些关键的必要的文档,作为开发任务的一部分,分配时间,应该会好一点。

    2019-04-03
    2
  • bearlu
    谢谢老师,上一期,按你提示,写了一个自动化静态代码检查工具,省了好多时间,现在学习机器学习也按项目来划分,将机器学习的每个知识点放到看板上。每完成一个就拿掉一个,感觉好很多。

    作者回复: 👍👍
    很高兴看到你能学以致用,并且有效果!

    2019-04-02
    2
  • 小老鼠
    1、就像测试代码一样,文档更新管理有什么好的建议,多久更新一次文档?2、如何理解代码就是最好的文档,代码可以替代文档吗?3、如何甄别无意义的文档?

    作者回复: 文档的更新通常是两种方式结合:
    1. 即时更新,在内容发生变化时即时更新,或者发现文档不正确直接更新
    2. 定期更新,根据团队的特点,定期例如每个月对关键文档进行审查和更新,至于周期设为多久,取决于你的团队能容忍多久不更新的文档

    文档的更新要尽可能简单方便,不宜过于繁琐,当更新文档的成本过高,就会越发的没有更新文档的动力。

    代码不能替代文档,好的代码可以帮助你理解代码。代码的问题在于很难直接通过代码看到全局架构,必须要配合有文档来从整体说明整体的架构。

    为什么有人说代码就是最好的文档呢?并不是代码能替代文档,而是说阅读好的代码,能帮助你快速的理解代码的含义,不需要额外有文档说明;还有就是一些类似于繁琐的一步步的操作部署文档,完全可以用自动化脚本代码替代,从而不需要文档或只需要简单的文档。

    没有价值的文档即无意义的文档!

    2019-09-12
    1
  • 老张
    写文档是一个梳理过程!
    说出来的东西逻辑性不足 错误不少,写文档的过程是一个优化、排错、提炼的过程,是思维由混乱变为条理的过程,不可或缺。
    非常赞同文中的方法:由脑图而ppt,再到文档分节,然后补充内容。

    作者回复: 🤝是的,写文档从粗到细比较好些

    2019-04-16
    1
  • 晓伟呢。☀
    老师,我觉得一个项目中,文档应该分阶段、分角色;比如在项目开始时,项目经理应该写什么文档、产品经理应该写什么文档、开发应该写什么文档等等。但是对于这个我们公司做的很不规范、很模糊,一般都是项目经理兼职产品经理,甚至开发兼职项目、产品的角色。所以您这边能帮我们总结一下吗?

    作者回复: 可以参考我给hua168留言的回复和给你另一条留言的回复。

    2019-04-09
    1
  • ownraul
    在开发过程中,比较习惯将一些重要的point归纳后罗列出来,因为有时很简单一句描述需要的代码并不少,过一段时间从代码中反推逻辑还是需要花些时间,不如直接写出来,或者的方法就是直接抽到一个方法中,让方法名来说明

    作者回复: 赞,谢谢补充分享👍

    2019-04-03
    1
  • 一路向北
    我们的项目文档基本上是以协议和流程为主,写这类文档的时候,实际上已经把项目的每一个细节都考虑清楚了,经过几次的review之后,后面的项目实现就是根据文档的内容再继续细化,一旦遇到不太清楚的地方,再回头翻阅文档,也很容易知道当初设计的时候是怎么一回事。
    套用格式确实是一个比较好的方式,填空总是比直接写作文要简单的多,而一旦整个空都填满之后,再继续润色,细化那又会比一开始简单些。
    写文档,记笔记等,用对工具还是很重要的。

    作者回复: 👍有价值的总结分享!

    2019-04-02
    1
  • Geek_long
    深有体会,没有文档的项目,对于项目的维护和交接代价太大了。
    2019-04-02
    1
  • 拉欧
    这节课很实用,为什么写文档?为什么写不好文档?为什么不想写文档?怎样写文档?这是程序员特别是高级程序员始终面对的问题

    作者回复: 是的,写文档没那么难,但是意义很大!

    2019-04-02
    1
收起评论
23
返回
顶部