查看原文
其他

老子写个代码而已,凭什么还要我写文档?

鱼皮 程序员鱼皮 2024-01-21

大家好,我是鱼皮。前段时间,我们团队在做 鱼聪明 AI 项目时,2 名开发同学竟然因为 “写文档” 吵起来了。

开发 A:这个项目是敏捷开发,我得赶紧写代码、快速上线,哪有空写文档?

开发 B:你不写文档,很多业务信息我就不了解,出了问题你背锅?!

开发 A:我给你讲一遍就完了,写文档多麻烦?大不了你把我的话记到文档上!

开发 B:你厉害,我给你竖大拇哥 👍🏻

。。。

作为一名经常写文档、并且认为写文档至关重要的程序员,听到他们的友好交流后,我决定要写下这篇文章 ——  分享写文档的经验和方法。因为我认为,无论是个人还是团队,无论是在学习、工作、还是项目中,无论对程序员、产品经理、还是项目管理者,做好文档沉淀都是至关重要的。我也真心希望未来和我合作的同事,不要把项目的信息和代码口口相传,而是能够做好分类整理,让大家高效协作。

下面我会给大家依次分享:为什么要写文档?怎么写出好文档?怎么管理好文档?

什么是文档?

文档是记录、储存和传递信息的载体。

我们的项目需求表、系统的设计方案、某某调研报告、某次会议记录、解决过的 Bug,甚至是学某个视频教程时随手记录的笔记,都是文档。

为什么要写文档?

从文档的定义出发,我们就已经能意识到文档的基本作用了。

  • 记录信息:收集临时的信息
  • 储存信息:防止信息丢失和遗忘
  • 传递信息:把信息和他人共享

我们的人脑容量有限,不可能记忆所有信息,而写文档,本质上就是在打造属于我们的第二大脑。

像我的脑容量是比较小的,所以我有随手记录、随手写文档的习惯,有的时候走在路上有个好点子都立刻掏出手机记下来。

文档对项目的价值

而对于做项目(尤其是企业大项目),文档又有更进一步的价值。

在项目初期,文档具有指导整个项目顺利推进的意义。如果将做项目比作盖摩天大楼,那么文档就是大楼的蓝图。没有蓝图,建筑工人只能盲目工作,能不能完成都很难说,更别提保证大楼的质量和安全了。

同样,在项目初期不写文档、没有系统的方案和执行计划,团队成员在开发过程中就会迷失方向,会经常出现延期、完不成、返工的情况。

看过我 原创项目直播 的同学应该知道,每个项目开始,我都会在文档上编写需求分析、方案设计、技术选型等内容。在做具体功能前,也是先在文档上写好设计实现方案,然后才去写代码。虽然写文档的过程会多花一点时间,但是会大幅降低整个项目的工时。

在项目中期,文档的意义是 持续 记录和追踪项目的状态,让信息在团队间公开透明,从而做出正确的选择、即时规避风险。

打个比方,把做项目当成跑马拉松,文档就是沿途的路标,会告诉大家跑到哪里了、接下来怎么跑;而如果前方有危险,路标也会给大家警示。如果没有文档,大家很快就跑散了,各自为战;一个人遭遇了风险,可能会拖垮整个团队。

在项目后期,文档的意义是帮助我们复盘总结、持续维护项目以及知识传承。

  • 复盘总结:通过阅读文档,我们能够回顾整个项目从诞生到结束的完整过程,从而分析出该项目成功或失败的原因,便于我们从中吸取经验,助力下一个项目的成功。
  • 持续维护项目:如果这是一个需要持续维护和更新的项目,有了文档(比如 Bug 手册、用户手册),项目出现问题时,哪怕换了一位项目维护者,也能很快地从文档中找到解决方案,不会出现 “一人离职、项目倒闭” 的情况。
  • 知识传承:沉淀好的文档,是前人宝贵的经验、教训、思路和方法汇总,非常值得学习,未来能给更多团队的同学带来启发和收获。

总之,写文档是一件利人利己的事,每写一个字,都是在生产价值。



在理解了文档的重要性后,我们应该怎么做好文档沉淀呢?

这里我们把文档沉淀进行拆分,需要做好两件事:

  1. 写出好文档(这是前提)
  2. 管理好文档

下面我们分别讲解。

怎么写出好文档?

想要写出好的文档,我们要先了解 “什么是好文档”,然后再去学习写文档的工具和方法。

什么是好文档?

我自己评判文档好坏的几个标准:

1)人能看懂、易于理解的

首先,你的文档是给 看的,如果是自己记录学习笔记,那么首先要保证自己能看懂;如果是在团队内共享文档,那么要保证别人能理解。如果本来一句话就能说清楚的内容,你在文档上用 20 句话来解释,这样哪怕你写了文档,别人可能还是直接来麻烦你本人。

2)结构清晰、易于查找的

好的文档,应该是别人从上到下扫一遍,就知道你在写什么、你想表达什么、我能从你的文档中得到什么、我在哪能找到我需要的内容。

就像这篇文章一样,我用了多级标题来划分文章的结构,你能直接通过目录大纲快速定位感兴趣的内容进行阅读。

3)内容完整、表述准确的

好的文档就像是项目中的一个模块,它应该是完整的、高内聚的,让人仅通过这个文档,就能解决自己的问题。

比如《某 Java Bug 的解决方案》文档,应该把 Bug 的起因、分析排查过程、解决方案、经验总结全部写出来。而不是说把这个 Bug 抛出来,怎么解决我不说~ 哎,就是玩~

另外,文档中的一些词汇和语句的表述一定要尽量准确,不能有歧义!

比如我们鱼聪明 AI 在最初评估成本时,写的是 “服务器若干、价格累积万元左右”,“若干” 和 “万元左右” 其实都是比较模糊的词汇,类似的情况多了就可能导致成本计算错误而亏损。后面我们把上述词汇改成了类似 “服务器 4C 8G 1 台,价格 1000 元 / 月”,实现更精细化的成本控制。

此外,好文档还可能有其他的标准,比如面向用户的产品文档,应该保证文档整体的风格、排版一致,给读者带来最佳的体验。文档写得好,也会提升用户对团队的认可度,从而更愿意使用团队的产品。

写作工具

工欲善其事必先利其器,在介绍写好文档的方法前,先分享一些写作工具。

多年以前,写文档基本都是用 Word,但 Word 其实是有很多的问题和不足的。比如要自己手动调整格式、同一份 Word 文档由于兼容性问题在另一个电脑上打不开或者排版错乱等等。

所以现在我强烈推荐大家学习 Markdown(一种轻量级标记语言),可以让你用同一套语法轻松编写出排版、格式一致的代码。

比如用 “## 二级标题” 来表示二级标题,用 “> 引用” 来表示引用文案等。

现在很多编辑器软件都支持 Markdown,比如我们平时用的 VS Code、JetBrains 全家桶。但如果要选择一个体验最好的本地 Markdown 编辑器,我推荐大家使用 Typora,这也是自己用了多年的软件。

在写文档的过程中,也经常需要一些绘图来辅助理解,比如流程图、架构图等等,可以使用在线工具 Draw.io、经典软件 Visio 等。如果需要绘制思维导图,可以使用 XMind。如果要生成一些配图,可以使用目前很火的 Midjourney(或者我们的鱼聪明 AI)。

如果你需要把文档发到其他自媒体平台,可以直接把 Markdown 内容复制粘贴到 mdnice 网站中,它会自动帮你生成精美排版的文章。

此外,随着 web 前端技术的发展,线上文档写作网站也越来越强大,如果要团队协作、实时共享文档的话,可以选用语雀知识库、腾讯文档、飞书文档等工具。

方法

“抄”

首先,想写好文档,要做的第一件事是 “抄”。

哦不,读书人的事,应该叫 “学习借鉴”。

如果你不会写文档,比如项目文档、设计文档、用户手册,怎么办?

很简单,到网上找优秀的 成品 ,去模仿。

不单单是写文档,做自媒体、做产品、写论文、学手艺,你想做好任何事情,第一件事都应该是:看看别人怎么做的,向别人学习。

  • 你要开发网站,就去网上找现成的网站
  • 你要做视频,就去网上找爆款视频

这是最简单的道理,很多东西都有前人做过,所以哪怕别人不分享教程,只要你去模仿,用点心也能完成。

再加上现在开源文化盛行,很多项目和文档都在 GitHub 等平台公开可见。当你要写一个文档时,直接先复制一下知名项目的 README.md 文件,然后把原本的目录大纲保留,把内容换成自己的,就得到了一份很标准的文档,就这么简单。

等你阅读和编写的文档多了,自然也能形成一套属于自己(团队)的写文档方法。

写作流程化

很多人讨厌写文档,就是因为感觉没有思路、无从下笔、完全不知道写什么。

我以前也常常是新建一个空白文档,然后对着它发呆。。。

但后来随着写作次数越来越多,我也修得了一套能够快速写出内容的方法,我把它称为 “写作流程化”。

什么叫流程?你去食堂买早饭,先排队、再买包子、再打豆浆、再找座位,这就是一个刻在 DNA 里的流程。

如果你也能有一套明确的写作流程,那么写作就像你买早饭一样简单。

具体怎么做呢?

1)先想清楚文章的结构,根据主题写出大纲

比如我在写这篇文章时,先写了 “什么是文档?为什么写文档?怎么写出好文档?怎么管理好文档?” 这几个小标题,把整篇文章的框架定下来。而不是从上到下漫无目的地去写,想到哪儿写到哪儿。

写大纲的过程本身就是在培养你的结构化思维 —— 把复杂的问题进行结构化拆解。如果你发现自己写大纲都很困难,那么不妨尝试把时间线作为大纲,按照由远及近的顺序,依次去写你各个时期的想法。

2)填空

只要确定了大纲,你就可以有 100% 的信息,这篇文章你必然能写完。因为剩下要做的就是往每个章节下填空就好了。

类似于有个导师给你规划好了你要做哪些事,你就有了个目标,更容易坚定地执行下去。

3)优化

写完大致的内容后,我们要整体读 2 - 3 遍文档,进行适当地优化。

就像我们写代码一样,虽然功能是完成了,但是代码可能写得比较烂,提交代码前得再改改。

列举一些常见的优化点:

  1. 修改错别字
  2. 小标题间增加关联语,承上启下,使内容更连贯
  3. 重点前置,把文档的关键信息放到开头,吸引人阅读
  4. 图文并茂、多用比喻,让文档更易于理解

这一套流程走下来,一篇完善的文档就诞生了。

持续优化

无论是自己写学习笔记、还是项目文档、用户手册,都不是写完一版就结束了的。好的文档是需要持续优化迭代的,如果有人指出了问题或者文档内容有过期,应当即时修复处理。不然错误的文档不仅不能帮助到人,还会产生误导。

像我们在开发鱼聪明 AI 的过程中,就很不幸地参考了一篇胡说八道的过期文档,让本就不富裕的团队雪上加霜。

积累

经常有朋友问我:鱼皮你平时又上班又高产胜母猪,怎么做到的?

其实我有一个习惯,就是会把生活中觉得有趣的事、或者突然想到的灵感记录下来,每隔一段时间去整理一下,后来我惊喜地发现,有些碎片化的内容竟然可以串起来讲,组成一篇文章。

就像打游戏一样,你想刷的装备一直出不来,你不在乎的装备碎片反而攒了一大堆。结果有天,你发现碎片都能够合成完整的装备了,竟然还挺好用,这就是无心插柳柳成荫吧。

写文档也是,哪怕你无法写一篇全面系统的文档,在你工作中遇到 Bug 的时候,随手开个文档记录下来;再遇到 Bug 的时候,就再打开之前的文档记录下来。次数多了,稍加整理,一篇高质量的文档不就来了?

举例

以我们的鱼聪明 AI 来举例,刚开始写项目立项文档时,按照上述的 “流程化” 方法,先定了文档大纲:

  1. 为什么做?项目背景
  2. 做什么?需求分析
  3. 怎么做?设计方案
  4. 具体怎么做?工作安排等等

然后才是一条一条地去补充完善,之后在每次开会和上线后,再持续更新完善一下这个文档。

完善文档的过程中,我也会看到很多之前记录的内容,提醒着自己在做这个项目的过程中不要走偏。

怎么管理好文档?

随着我们项目的不断迭代,文档数也越来越多、越来越零碎,怎么管理好这些文档,让大家需要阅读时能快速找到,这是个大问题。

尤其是对于大项目来说,假如 100 个人一起开发,每人写 10 篇文档就是 1000 篇文档,怎么对这 1000 篇文档进行管理呢?

要先有一个意识:尽早发现问题,会比后期解决问题的成本要低很多。

所以管理好文档这件事,应该主要靠 “前期的策略” 和 “中期的持续优化”,而不是后面再去人工整理大量的文档。

代码屎山就是这么来的,烂代码堆得越多,越没人敢动。

所以首先,我们在开始项目前,就要建立好一套规范的 文档体系

1)文档线上化

只要是和项目 / 工作相关的文档,不要让大家在本地去写,而是直接用线上文档去 实时协同 。很简单的道理,你本地改了一段话,别人本地也改了相同文档的一句话,那最终以谁的为准?

像我们 鱼聪明 AI 的所有内部文档,都是使用语雀知识库来托管的,所有项目的信息在团队内部公开透明,从而尽最大地可能性消除信息差。

而且线上知识库还有一个好处,就是查找搜索方便,整个知识库的内容一键随便搜。

2)分组

随着文档或知识库越来越多,必然就会给大家的查找造成负担。所以我在 最开始 就给所有团队内部的知识库都按主题做了分组,如下图:

每个知识库下的文档,也建立了相应的分组:

当然,分组这个操作也是需要持续做的。如果刚开始没有办法预估会有哪些分组,那就等后面需要分组的时候,即时新建就好。

3)访问控制

所谓访问控制,就是让部分成员只能看到部分文档。这么做不仅是为了安全,也可以让大家尽量聚焦在自己的工作上,更能找到自己需要的文档。

目前我们鱼聪明 AI 团队的每个知识库都是有严格的访问控制的,只有大家需要看某个知识库时,我才会给他们开对应的权限。当然这也不是说要限制团队成员的学习,如果他对某个知识库感兴趣,可以直接申请查看。

主流的线上文档软件基本都支持访问控制和权限管理,实现上没有什么难度。

4)培养团队文档文化

还记得这篇文章开头我给大家讲的自己的故事么?有些人可能是没有写文档的意识、或者就是不爱写文档的!如果这个人又是项目的重要贡献者,那么他个人掌握的、团队不清楚的信息就会越来越多,最终就会出现 “他的代码别人动不了”、“他一走项目就完蛋” 的情况。

为了把这种风险扼杀在摇篮里,我反复跟团队的成员强调,一定要多写工作文档、即时同步信息,甚至对于一些重要的工作,我会把文档作为大家工作成果的一部分。慢慢地,大家就养成了写文档、文档分类的习惯。



以上,足足写了 5000 多字,能看到这的朋友也不容易啊。希望大家能够意识到文档沉淀对于团队和项目的重要性,在之后的学习工作中多记录多总结,管理好自己的文档库。

往期推荐

我入伙了!

搞台虚拟机玩玩!

看完这个,我直接把 SQL 刷通了!

一次很意外的网站故障经历。

实习天天crud,很迷茫...

手写 OJ 系统,真的很难么?

继续滑动看下一个

老子写个代码而已,凭什么还要我写文档?

鱼皮 程序员鱼皮
向上滑动看下一个

您可能也对以下帖子感兴趣

文章有问题?点此查看未经处理的缓存