职场大瓜，快进来围观！！！！

 

❝点击关注上方公众号，发现更多精彩内容等你来发现❞前言前段时间，团队有成员离职，在做工作交接的时候,，我和开发人员A有了以下对话：我：工作流引擎roadflow有没有什么东西需要交接给我的前端开发A：没有，当时研究到一半就停了，很多功能做不出来

我：那有没有研究过的文档说明或者demo的代码前端开发A：呃，也没有我：..........

作为一名经常写文档、并且认为写文档至关重要的程序员，跟团队成员交接工作时友好交流之后，我决定要写下这篇文章 ,分享写文档的经验和方法因为我认为，无论是个人还是团队，无论是在学习、工作、还是项目中，无论对程序员、产品经理、还是项目管理者，做好文档沉淀都是至关重要的。

我也真心希望未来和我合作的同事，不要把项目的信息和代码口口相传，而是能够做好分类整理，让大家高效协作下面我会给大家依次分享：为什么要写文档？怎么写出好文档？怎么管理好文档？什么是文档？文档是记录、储存和传递信息的载体。

我们的项目需求分析表、系统的设计方案、某某调研报告、某次会议记录、bug报告书等等，甚至是学某个视频教程时随手记录的笔记，都是文档文档不限形式、不限载体为什么要写文档？从文档的定义出发，我们就已经能意识到文档的基本作用了。

记录信息：收集临时的信息储存信息：防止信息丢失和遗忘传递信息：把信息和他人共享我们的人脑容量有限，不可能记忆所有信息，而写文档，本质上就是在打造属于我们的第二大脑我把文档想象为数据库，文档的标题就是我的。

主键，通过主键就能提取我记录的文档信息文档对项目的价值在讨论这个文档对项目的价值时，如果有幸参与过CMMI评估的人员就非常有感触，因为在CMMI评估实践证明：在进行CMMI评估之前，制定一个正确的评估计划并将其文档化，确保有一个富有经验的、受过培训且具有适当资格的小组能被用来评估，为执行评估过程做准备，是十分必要的。

我们所说的文档化CMMI评估计划的结果，包括：要求，协定，估价，风险，剪裁方法，以及与评估相关的实际考虑（例如：日程安排，后勤，组织的背景信息），里面要产出的文档多不胜数项目初期文档具有指导整个项目顺利推进的意义。

如果将做项目比作盖摩天大楼，那么文档就是大楼的蓝图没有蓝图，建筑工人只能盲目工作，能不能完成都很难说，更别提保证大楼的质量和安全了同样，在项目初期不写需求文档、没有系统的设计方案和执行计划，团队成员在开发过程中就会容易迷失方向，会经常出现延期、完不成、返工的情况。

项目中期文档的意义是 持续记录和追踪项目的状态，让信息在团队间公开透明，从而做出正确的选择、即时规避风险打个比方，把做项目当成跑马拉松，文档就是沿途的路标，会告诉大家跑到哪里了，接下来怎么跑；而如果前方有危险，路标也会给大家警示。

如果没有文档，大家很快就跑散了，各自为战；一个人遭遇了风险，可能会拖垮整个团队项目后期文档的意义是帮助我们复盘总结、持续维护项目以及知识传承复盘总结：通过阅读文档，我们能够回顾整个项目从诞生到结束的完整过程，从而分析出该项目成功或失败的原因，便于我们从中吸取经验，助力下一个项目的成功。

持续维护项目：如果这是一个需要持续维护和更新的项目，有了文档（比如 Bug 手册、用户手册），项目出现问题时，哪怕换了一位项目维护者，也能很快地从文档中找到解决方案，不会出现 “一人离职、项目倒闭” 的情况。

知识传承：沉淀好的文档，是前人宝贵的经验、教训、思路和方法汇总，非常值得学习，未来能给更多团队的同学带来启发和收获关于知识的传承我还需要展开说说，以我们公司为例，同一项目小组完成项目通常具备项目相似性、因为它们业务上大体相同，本应该完成一个项目后，能快速生产相同的业务的类似产品，成本应该会不断降低才对的，但是据我观察，由于团队内部并没有搭建知识库平台，团队成员之间也没有养成写文档的良好习惯。

就容易出现以下情况：在同一个bug中反复踩坑，浪费工时团队某个开发人员稍微不够主动向上反馈，很容易卡在同一个难点中，消磨时间，等到deadline时间完不成了，最后才反馈，然而发现其实这个问题早就其他成员被解决了，前面的消耗都是在浪费工时

团队旧成员离职之后，无法留下他曾经过的bug处理步骤和完成的难点攻克的技术，因为没有文档交接，这个人员离职成本增加了针对新入职的成员，所有项目的bug和难点都需要重新踩一遍，以及口口相传一遍，新成员培养成本也增加了。

文档对个人的价值文档是一个载体，即便你所有的文档都是为项目、为公司而写的，都会伴随你的职业生涯文档只要被你生产出来后，你上传到公司的知识库，那就是企业的财富，你留在自己的笔记本里面，那就是你职业生涯的财富，即便你去到那家公司，甚至不做这个行业了，只要你的文档还存在，你都可以迅速吸收你曾经写在文档上的知识内容。

针对个人，文档价值如下：巩固知识，牢记知识增强自己的社会竞争力，在互联网内卷时代，你记得越多，知识面越广，竞争力越强，抗风险能力也越强综上所述，写文档是对项目来说都是一件利人利己的事，每写一个字，都是在生产职业价值。

怎么写出好文档？什么是好文档？我自己评判文档好坏的几个标准：1. 人能看懂、易于理解的首先，你的文档是给 「人」 看的，如果是自己记录学习笔记，那么首先要保证自己能看懂；如果是在团队内共享文档，那么要保证别人能理解。

如果本来一句话就能说清楚的内容，你在文档上用 20 句话来解释，这样哪怕你写了文档，别人可能还是直接来麻烦你本人2. 结构清晰、易于查找的好的文档，应该是别人从上到下扫一遍，就知道你在写什么、你想表达什么、我能从你的文档中得到什么、我在哪能找到我需要的内容。

就像这篇文章一样，我用了多级标题来划分文章的结构，你能直接通过目录大纲快速定位感兴趣的内容进行阅读我观察到我的团队成员在刚开始写文档的时候，很容易写成流水账，就是标题结构模糊、层次不清楚、重点是各种截图比例大小不一，导致整个文档七零八落，看得很难受。

3.内容完整、表述准确的好的文档就像是项目中的一个模块，它应该是完整的、高内聚的，让人仅通过这个文档，就能解决自己的问题例如下面截图的《表单嵌入-app篇》，它不但没头没尾，不知道要表达什么东西，他原本应该要清晰说明：。

如何接入、接入后出现问题、分析排查过程、解决方案等经验总结全部写完整，而不是说简单写几个流水账，虽然有写总会比没写要好，但是没有表达准确的内容还是会造成理解困难

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

首先，想写好文档，要学会做的第一件事是 「模仿」，也可以是说“学习借鉴”、难听点可以说是“抄”如果你不会写文档，比如项目文档、设计文档、用户手册，怎么办？问问公司有没有模板给你参考网上找找优秀的模板，去用心「模仿」。

看看身边有没有写文档较好的同事或者朋友，大胆地“抄”他们的格式不单单是写文档，学习前后端技术、做产品、写论文、学手艺，你想做好任何事情，第一件事都应该是：看看别人怎么做的，向别人学习你要开发网站，就去网上找现成的网站、去B站找视频学习、去github找开源项目。

一切技术的提高都是从「模仿」开始的包括我们的“两弹一星”的钱学森，伟大的科学家，在研究导弹和原子弹的外形和原理时，也是向前苏联学习，看他是怎么做，我们也模仿怎么做，这是我们中国人的“优良传统”，华强北的名头也让西方国家的奢饰品生产商家咬牙切齿的，这得益于我们善于「模仿」

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

等你阅读和编写的文档多了，自然也能形成一套属于自己（团队）的写文档方法写出好文档的方法2：写作流程化很多人讨厌写文档，就是因为感觉没有思路、无从下笔、完全不知道写什么我以前也常常是新建一个空白文档，然后对着它发呆。

但后来随着写作次数越来越多，我也得出一套能够快速写出内容的方法，我把它称为 “写作流程化”什么叫流程？你去楼下买早餐，要先排队、再买包子、再打豆浆、再找座位，这就是一个刻在 DNA 里的流程如果你也能有一套明确的写作流程，那么写作就像你买早餐一样简单。

具体怎么做呢？1. 先想清楚文章的结构，根据主题写出大纲比如我在写这篇文章时，先写了 “什么是文档？为什么写文档？怎么写出好文档？怎么管理好文档？” 这几个二级标题，把整篇文章的框架定下来而不是从上到下漫无目的地去写，想到哪儿写到哪儿。

写大纲的过程本身就是在培养你的结构化思维 —— 把复杂的问题进行结构化拆解如果你发现自己写大纲都很困难，那这个时期你就要看多点优秀案例，看看别人的大纲一般怎么写，然后尝试自己落笔写一下，刚开始都会写不好，但是写多了，结构化思维就已经培养出来了。

我常常跟我团队成员说，写大纲就跟你做职业规划一样，每个标题代表的是你每个阶段计划安排，你得提前规划好，当遇到当前标题内容没有按时完成时，要及时调整目标，把大的标题划分更小的标题去完成例如我们写文档时，写了一级标题、二级标题的大纲之后，在做下面第二步的填空题的时候，发现一个二级节点无法完整表达我的意思，那么我们就要及时拓展更多三级标题出来，及时调整你的目录结构（人生规划）。

2. 做填空题只要确定了大纲，你就可以有 100% 的信息，这篇文章你必然能写完因为剩下要做的就是往每个标题下做填空题，把标题所表达能内容，给它拓展完成即可类似于有个情感导师给你规划好了你要做哪些事，你就有了个目标，更容易坚定地执行下去。

3. 优化内容写完大致的内容后，我们要整体读 2 - 3 遍文档，进行适当地优化就像我们写代码一样，虽然功能是完成了，但是代码可能写得比较烂，提交代码前得再改改列举一些常见的优化点：修改错别字小标题间增加关联语，承上启下，使内容更连贯。

重点前置，把文档的关键信息放到开头，吸引人阅读图文并茂、多用比喻，让文档更易于理解这一套流程走下来，一篇完善的文档就诞生了4. 持续优化无论是自己写学习笔记、还是项目文档、用户手册，都不是写完一版就结束了的。

好的文档是需要持续优化迭代的，如果有人指出了问题或者文档内容有过期，应当即时修复处理不然错误的文档不仅不能帮助到人，还会产生误导怎么管理好文档？随着项目不断迭代或者个人年龄的增长，文档数目会越来越多，越来越零碎，怎么管理好这些文档是个大问题。

针对个人管理来说十分容易解决，只要保证一下几点内容：使用通用的文档格式，能在不同的系统平台，不同应用软件上，正常显示即可确定好写文档的工具软件根据知识点，不断细分，做好分组管理工作下面主要讨论团队、项目之间如何管理好文档，建立属于团队一套规范的 。

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

所以现在我强烈推荐大家学习Markdown（一种轻量级标记语言），可以让你用同一套语法轻松编写出排版、格式一致的代码比如用 “## 二级标题” 来表示二级标题，用 “> 引用” 来表示引用文案等现在很多编辑器软件都支持。

Markdown，用这个Markdown语言写出来的文档，能够让我一分文档，同时在微信公众号、vuepress、wikijs、docsfiy等技术平台上使用而且很多编辑器都能实现流程图、架构图、思维导图的嵌入，让你的文档内容显得更加丰富。

此外，随着 web 前端技术的发展，线上文档写作网站也越来越强大，如果要团队协作、实时共享文档的话，可以选用语雀知识库、腾讯文档、飞书文档等工具2. 统一写作工具我在写作的道路上用过很多笔记工具：印象笔记（弃用）。

有道云笔记（偶尔用）vscode(最常用)Typora（偶尔用）如果大家个人知识库的话，我个人会更加推荐Typora,界面优化，目录清晰，更容易掌握，写作门槛相对较低个人完全可以在本地写完文档之后，迁移到项目提供的在线平台就行，也可以统一在团队搭建的在线平台上写文档。

3. 搭建知识库文档线上化只要是和项目 / 工作相关的文档，不要让大家在本地去写，而是直接用线上文档去 「实时协同」 很简单的道理，你本地改了一段话，别人本地也改了相同文档的一句话，那最终以谁的为准？因此团队管理文档至少要搭建内部使用的知识库，支持

Markdown语言，让大家都在线上写文档，降低写作门槛而且线上知识库还有一个好处，就是查找搜索方便，整个知识库的内容一键随便搜分组随着文档或知识库越来越多，必然就会给大家的查找造成负担所以我在 「最开始」

就给所有团队内部的知识库都按内容做了分组

当然，分组这个操作也是需要持续做的如果刚开始没有办法预估会有哪些分组，那就等后面需要分组的时候，即时新建就好访问控制所谓访问控制，就是让部分成员只能看到部分文档这么做不仅是为了安全，也可以让大家尽量聚焦在自己的工作上，更能找到自己需要的文档。

我们团队还对成员的编辑权限进行了限制，避免同事们不小心改错了别人的文档主流的线上文档软件基本都支持访问控制和权限管理，实现上没有什么难度培养团队文档文化还记得这篇文章开头我给大家讲的自己的故事么？有些人可能是没有写文档的意识、或者就是不爱写文档的！如果这个人又是项目的重要贡献者，那么他个人掌握的、团队不清楚的信息就会越来越多，最终就会出现 「他的代码别人动不了」、「他一走项目就完蛋」 的情况。

为了把这种风险扼杀在摇篮里，我反复跟团队的成员强调，一定要多写工作文档、即时同步信息，一切的研发任务都要产出价值，文档只是一个展现成果方式之一，甚至对于一些重要的研发调研工作，我会把文档作为大家工作成果的一部分。

我希望能慢慢培养出他们的写文档的良好习惯总结不知不觉，洋洋洒洒写下了5000+字，能看到这里的朋友也不容易啊，希望我团队的小伙伴看到之后，能重拾写作的信心，也同时也希望其他小伙伴看到这篇文章之后能够意识到文档沉淀对于团队和项目的重要性，在之后的学习工作中多记录多总结，管理好自己的文档库。

点个“在看”不失联

免责声明：本站所有信息均搜集自互联网，并不代表本站观点，本站不对其真实合法性负责。如有信息侵犯了您的权益，请告知，本站将立刻处理。联系QQ：1640731186