技术文档写作速成指南

鲁迅说的好：文档是程序员进步的阶梯！

虽然鲁迅先生并没有说过这句话，但是对于工程师来说，写文档还是非常重要的~

重要的事说三遍：重要的事，重要的事，重要的事！

1、写文档可以帮助我们整理思考过程

当遇到一个问题的时候，我们聪明的脑子里可能突然迸发出很多想法，他们之间可能层层递进，也可能彼此毫无关系。如果没有及时通过工具记录下来，后面很可能就忘掉了。

如果使用文档记录，不仅不怕遗漏，而且经过简单的整理就可以梳理出一个脉络。这时可能发现有些重点问题需要深入挖掘，而有些问题并没有像开始想的那么重要。

2、写文档可以帮助我们提高沟通效率

先想一下我们目前拥有的沟通方式都有哪些呢？

• 面对面：这是最直接的沟通方式，效果最好，但是缺点也很明显：来一个人就要重复再说一遍
• 通讯软件：对比“面对面”的优势是，除了第一次沟通都可以转发聊天记录
• 文档：准备一个文档，减少常见问题的人力沟通成本浪费
• 代码：最简单，废话少说 show me your code。但是这种方式不仅费时间，而且还不一定能看懂代码

从上述分析可以看出，虽然使用文档的沟通方式准备成本最高，而且还需要逐步完善、不断更新，但是随着沟通人数的增加，效率优势会更加明显。

3、写文档可以提高对“新人”的友好性

这里的“新人”不止代表刚刚入职的小萌新，还包括因为工作交接负责不熟悉的新项目的老师傅，甚至面对两个月前你写的代码时的自己。

好叭，我们都认可写文档是一件好事情，但是要就事论事嘛，有的情况就不用写文档阿

A同学：项目很简单/开发者很少，没必要写文档 ❌

• 未来是难以预料的，项目的复杂性会随着项目的持续而不断增加，慢慢超出预期。
• 前期项目简单，文档很快就能写完。但是如果一直拖延，写作的成本就会越来越大。

B同学：时间太紧了没时间写文档，以后有空再补吧 ❌

• 工作的产出不应该只有代码，也应该包含文档。
• 不要把文档当做走形式、面子工程，其实用好文档，它会变成工作中很好的辅助工具。
• 写文档不是单纯的增加工时，思路清晰后，写代码的效率更高。

那到底什么时候需要写文档？

最简单的判断方式：不能“秒懂”的地方，都应该留下文档。

时间有限，小孩子才做选择，我写文档就要又快又好！

下面用模拟需求开发过程的方式，介绍写文档的流程~

1、【准备】了解PRD

与开发需求时一样，写文档之前也要了解文档的需求：

• 明确写作目的：不同目的有不同的侧重，明确目的也便于事后衡量成功是否达标。比如，如果想写一个项目交接文档，需要事无巨细的记录所有工作中涉及的内容，与项目相关的注意事项，力求全面详尽；如果想写一个项目推广手册，那就要介绍项目是做什么的，与竞品的对比和优势，吸引读者的关注、获取读者的好感。
• 明确文档受众：也就是了解读者的技术背景，使用读者可以看懂的表达，可以让文字形成更有效的传达。

2、【调研】康康别人咋写的

在开始写文档之前，需要了解一下此类文档的主流框架。

如果组内已有模板，直接使用即可；如果没有，可以查阅同类产品文档，掌握基础框架。可以多收集写相似的资料，不一定在什么时候就可以给你提供一些灵感哦！

一般的文档需要包含下列内容：

• 项目信息：项目名称、版本号
• 历史修订信息：修订人、修订时间、修订原因
• 文档介绍：概述、背景
• 注意样式：清晰的文档结构，统一的排版格式

3、【框架搭建】给我的变量起个名

了解了主流文档框架，就要开始梳理我的文档结构了！这一部分的主要工作是写好文章的标题，如果要插图可以先用符号和简要描述代替，以免全局审视时发现有些图片不需要，浪费了当时作图或找图的时间。

如何衡量标题是否合适呢？下面提供几个判断标准：

• 准确的标题：标题需要可以概括文章/段落的内容，不可跑题
• 有序的标题：使用字体大小、缩进关系，来表达标题之间的顺序与关系
• 提纲可以概括文章内容：在前两点都完成的情况下，提纲自然可以概括文章内容。但是需要注意，标题间的嵌套关系不要太深。就像不要嵌套太多if-else一样，需要及时把一些深层内容提取成单独的一段。一般与其他内容独立的内容、特别重要的内容、需要深入剖析的内容，都可以独立成段。

4、【写作】开始写bug啦

这个阶段的主要工作是向骨架中填充内容，并且补充图片资源。

需要注意以下事项：

• 段落内需要有逻辑：常用逻辑有总分、总分总、并列、递进等等
• 标记重点内容：通常使用明亮的颜色、加粗、图标等方式
• 配图清晰：图片面积不要太大，以防喧宾夺主；针对图片内容可以使用高亮或者文字描述，说明重点内容
• 其他注意：用词友好，语法正确，标点使用等细节

5、【评审】Code Review

文档写完了并没有结束，还需要好心的小伙伴帮忙评审一下。一般分为三个评审方向：

自我评审：检查错字、标点等低级错误，节省其他评审人的时间
语法评审：检查内容是否准确有效，是否完整、有误遗漏信息
风格评审：检查语言是否简洁，用词是否得体，描述是否易懂

6、【更新】搞，搞二期！

其实前面已经完成了一次写作流程，但是只要项目还在更新，文档就要一直维护，不能给用户一种“文不对题”的感觉。当然，如果熟练上我上面的流程，那维护文档也不是一件困难的事情啦~！

1、精简之美

首先介绍一项内容，要仅提供一个文档入口。如果同时看到很多链接，会增加读者阅读的心理压力，进而转化为排斥情绪，那作者在第一步就输了 o(╥﹏╥)o

• 文档需要包含最简单可用的案例，让用户可以快速得到一个可体验的demo
• 如果有高级用法，要与简单的指南分开，并且提供可直接验证的特性
• 对于专业术语或者自定义词汇，复述定义可以有效降低阅读难度

针对文章内，也要尽量用词简洁。文档不是写小说，不需要加太多的修饰词和无必要的语句重复。

可以参考《清晰优雅的风格课》中对「叙述简洁」的六条原则：

• Delete words that mean little or nothing.
• Delete words that repeat the meaning of other words.
• Delete words implied by other words.
• Replace a phrase with a word.
• Change negatives to affirmatives.
• Delete useless adjectives and adverbs.

2、排版之美

良好的排版可以提高专业性、增强页面效果，提高可读性、便于用户理解行文结构。

在《写给大家看的设计书》中对排版提出了四项基本原则：

• Contrast 对比原则：避免不同元素太多相似，要在视觉上制造突出的差异，也就是看起来完全不同
• Repetition 重复原则：相同结构的元素，使用相同的样式，制造视觉上的统一性
• Alignment 对齐原则：常用的是左对齐、居中对齐、右对齐
• Proximity 亲密性原则：内容相近的内容应该物理位置也解决

一般通过字体、字号、颜色、位置、特殊符号来实现，但是要注意：不同的元素差别一定要大，否则就是更糟糕的视觉冲突。

3、颜色之美

颜色是吸引读者注意力的利器，所以要把它用于强调而不是装饰。

有目的的使用颜色，可以告诉读者该看哪里，而不要为了个人喜好把文档写的五颜六色。一般使用三种颜色，如果页面颜色超过五种就会显得杂乱。

还要注意的问题是，颜色要获得读者的感情认同。一般红色都代表禁止、失败、标记，绿色代表通过、环保、安全，黄色代表警告、通知，这一点从emoji表情的配色也可以看出来：

• 红色系列：