🌄 前言
什么是好的文档？在我看来，不减分地表达清楚作者的意图，即是一个不错的文档，
- 从作者角度上讲，能够让读者快速、清晰理解作者要表达的内容。
- 从读者角度上讲，读者能够快速、清晰地了解到自己想要了解的内容。
那如何写好文档呢，先抛观点。
自顶向下地结构化表达 + 一点点的排版 = 一篇不错的文档
Talk is cheap. 先抛出自己写过的一些文档，你可以大概瞄一眼，如果觉得还算认可，就可以继续阅读，如果不认可，就也节约时间了。
🧑💻 工作
以我常写的技术方案为例，除去方案本身的设计时间，大概时间占比如下
- 定主题 10%
- 立框架 20%
- 填内容 60%
- 调排版 10%
除大家都熟练的填内容之外，其他部分比如排版，在刚开始时肯定会需要更多的时间，但用不了多久就不会再花更多时间，唯手熟尔。最后还是要先强调一下，每个人都有自己的写作习惯，不用刻意模仿，没有意义。写这篇文档的原因也只是把自己的经验分享出来，未必都对，仅供参考，欢迎讨论。
🎯 定主题
定主题这件事情其实很简单，写一篇文档一定是有所目的，这里想强调的是，写文档的时候要反复回看自己的主题是什么，偏离主题的讨论应当适当简化，这样才能让文档不那么冗余，别人读起来才会比较舒服。定主题的重点不在主题本身，而是有主题这件事情，即主题是什么不重要，重要的是存在主题&忠于主题。
文档的所有内容，都应当是为主题服务的。
这件事情看似非常简单，但在实操过程中却非常难以做到的。比如描写如何从北京到上海的技术方案，重点在于什么时间去、有哪些交通方式、有哪些优劣势，常见的错误就是写着写着，却花了大量的篇幅去讲飞机是怎么组成的、高铁是哪里制造的。
并不是说不能写这些东西，而是这些东西并不切题，读起来很容易有一种东一榔头、西一棒槌的感觉，如果真的觉得有必要说明一下，那更好的方式是一笔带过或者附加链接的形式。
🍢 立框架
文档并不会像长篇书籍一样拥有复杂的框架，通常目录就可以看做文档的主框架。但一个文档未必只有一个框架，恰恰相反，通常都会有多个框架。立框架不止是写全文之前，写每一具体的部分也可以先立框架，再写内容，有些框架是显式展现给读者的，有些框架则是作者仅用以写作的。
我以常写技术方案为例
框架 | 作用 | |
主框架 | 文档 | 以目录为中心，统领全文的行文逻辑 |
次框架 | 技术方案 | 以方案架构图/流程图为中心，统领技术方案的描述逻辑 |
产品方案 | 以PRD为中心，统领用户视角下的产品逻辑 |
立框架有以下几个好处
- 帮助自己梳理思路，防止遗漏要点
- 确保内容不会偏题，抓得住重点
- 抽象地看框架，更容易将事情调理顺
- 读者更容易理解作者的思考逻辑
框架的重点在于思考逻辑，而不是表达细节
举一个我实际改过的例子，文档背景大概是一些任务偶尔会存在网络抖动，进而导致任务失败，这些失败通常是可以通过重试解决，故我们希望建立一个自动重试机制，来避免用户受到这部分失败的影响。
- 项目背景
- 稳定性问题分类
- 可直接重试解决
- 重试不可解决，需手动处理
- 稳定性问题分类解决方案
- 重试可解决
- 机器问题被杀、环境依赖问题
- 网络问题
- 重试不可解决，需手动处理的方案构思
- 文件数过大导致任务超时
- 规则代码不当导致crash（数组越界等）
- 规则throw异常
- 数据指标
- 具体实施技术方案
- 项目目标
- 里程碑
主要有以下几个问题
- 内容维度
- 文档缺乏数据支撑，只知道有这种(网络抖动)情况存在，但是不知道占比多少，也没法预估收益多少
- 非重试能解决的问题显然不是这个方案要重点解决的问题，但却占据了相当的篇幅，偏离了主题
- 标题不够精简，包含了太多实现细节，"不像标题"，不了解背景的人也很难理解这些细节到底什么意思
- 对于技术方案整体没有一个完整的描述，所有的描述都在指向细节，读者很难有全局视角一以贯之
- 逻辑维度
这个逻辑并不是定死的，参杂了一些个人习惯，但目标是一定的，即下一节所讲的内容要符合读者的心理预期，不让人感觉到太过跳脱。不必追求逻辑的精妙，越简单的逻辑，反而越容易理解。
- 解决方案和技术方案本质上是一件事情，但却被拆成了两个小节，造成了内容的不连贯
- 目标应该紧随背景，只有讲明白目标是什么，读者才能跟着作者的思路实现对应的目标，以及提出相关建议
目标应该是事先定好的，而不是总结而来的，这样才能使得文章整体是自顶向下的。
- 逻辑上，先讲背景，让大家理解了背景，再讲目标，然后拆解目标，为目标提供数据支撑，再讲实现方案，最后定一些关键指标来评估效果。这样的逻辑上是相对比较顺的，阅读、理解也更容易。
- 美观维度
- 太多的细节，以及不像标题的标题，排版起来也不太美观
经过一番修改，对比前后
修改前
- 项目背景
- 稳定性问题分类
- 可直接重试解决
- 重试不可解决，需手动处理
- 稳定性问题分类解决方案
- 重试可解决
- 机器问题被杀、环境依赖问题
- 网络问题
- 重试不可解决，需手动处理的方案构思
- 文件数过大导致任务超时
- 规则代码不当导致crash（数组越界等）
- 规则throw异常
- 数据指标
- 具体实施技术方案
- 项目目标
- 里程碑
修改后
- 背景
- 目标
- 前期调研
- 数据统计
- 问题分类
- 流程现状
- 技术方案
- 概览
- 重试机制
- 数据指标
- 里程碑
- 相关文档
技术方案是研发同学最常要写的文档，你会发现上面这个模板几乎适用于各种技术文档，技术方案这类文档恰好也是模板化最显著的一类，按照大的框架来写，至少可以保证不会犯错。其实无论是不是技术文档，在叙事逻辑上，无论是文档、PPT、视频各种各样的形式，形式的变化其实都不影响叙事逻辑，自顶向下的结构化表达，是读者最容易快速理解的方式。
这就是我对框架的理解，框架只是思考叙事的结构，真的只是框架就好，不需要多么惊艳，只要能帮助作者、读者理清逻辑、不犯错即可。如果你细心，看下本文的目标结构，其实也是非常简单的。
能套模板了，为什么还会占用20%的时间？
答案其实隐含在前文里了，一个文档通常都会有多个框架，这里只是讲了主框架，在填内容的过程中，每个小节通常都可以有自己的框架，这是我认为立框架能占到20%的时间的主要原因。
🥗 填内容
结构化不应只体现在框架上，而是方方面面。
🛠️ 常见要素
🌄 背景
无论是写文档，还是写PPT，背景都是非常重要的环节，大家往往会低估背景描述的价值。写背景时，必须站在一个没有相关知识背景的读者的角度去描述。
最常见的错误就是，作者觉得自己的方案理所应当，所以背景就简单一两句话概括。绝大多数时候，你觉得一两句话能阐述清楚的背景，大概率是因为你具备充分的背景知识，对于一个不了解现状的读者来说，显然是无法理解的。精简、直观甚至巧妙的背景描述、案例列举，让读者能够快速了解并理解背景，是带动读者"入局"的关键。
作者和读者之间，通常会存在比较显著的信息差，而作为作者，需要有意识地减少这种信息差。
如果读者都不了解背景是什么，那他对你的想法/方案大概率是无法理解的，很容易不知所云。遇到比较多在评审时，总会有人提出一些看似角度刁钻的问题，作者不得不反复阐述问题背景。出现这种情形，归根结底是背景没有真正阐述清楚。加大在背景上的投入，绝对是一件非常值得的事情。
🎯 目标
让读者了解完背景之后，抽象地给自己以下要阐述的内容定下核心诉求，显式地强调出来，而不是让读者去猜、去感受，这样有助于读者了解这篇文档到底是要干什么。只有明确了目标，读者才能真正基于目标来了解后续内容的巧妙，或评估后续内容的合理性，提出有用的建议。带着目标阅读，可以显著地提高阅读效率。
🛠️ 方案
如何写好一个方案，我的答案依旧是自顶向下的结构化表达，先立框架，再填内容。
我通常会先画一个架构图，来梳理我以下要讲的内容的框架。
当然也有同学可能并不赞同这种图，觉得一眼看过去并不知所云，我依然推荐的原因如下
内在原因 (for 作者)
- 透过架构图，来梳理自己对于方案的描述逻辑，作用就是前文的立框架
- 帮助自己梳理思路，防止遗漏要点
- 确保内容不会偏题，抓得住重点
- 抽象地看框架，更容易将事情调理顺
外在原因 (for 读者)
- 人对图的接受程度要远大于大段文字
- 图可以帮助读者快速理清各元素之间的关系，对于关系的形象描述有着天然的优势
- 图的理解粒度，可粗可细
这是最主要的原因，无需读者一开始就仔细地理解整图，对整体系统能有个大体认识即可。
- 粗，可以统观整体设计，让读者事先有个宏观的认识 (自顶向下)，也是统领后文的框架
- 细，当读者读完方案细节后，反观图即会有更为清晰的认识，下次再讨论时，能够快速回忆起具体的内容
- 提升文档的专业度和权威性
- 懂，可以快速通过架构图来看其中的门道
- 不懂，从某种程度上至少让人愿意相信这是经过深思熟虑的
🏌️♂️实用技巧
🚧 先由少到多，再由繁至简
这个技巧还是一位大学老师教给我的，当你觉得一篇文章干货满满，大概率都是作者有意规避了一些冗词赘句。通常来讲，我们很难一次性写出一篇各部分内容笔墨都恰到好处的文章，那就不妨先顺着思路能写多少写多少，先有了内容，再去刻意地根据主题、框架来精简内容，这样相比写的时候总是担心是否偏题，思路会更顺畅一些，写作效率也会更高。
🩺 读者视角逐句通读
当你写完一个文档时，检查一下内容是否忠于主题、忠于框架。然后把自己当成读者，抛开自己的脑补，一字一句地通读文档，有些看似流畅的叙事逻辑，但是常常会伴随着作者大量的脑补，在读者看来则常常会是一头雾水，很多问题，只有当你作为一个读者时，才能体会到，语句冗余、逻辑不通，甚至只写了一半的句子。
🙅 避免口语化
文档不是小说，有些同学在写文档的时候会使用口语用的大白话，这个会让读者读起来非常奇怪且冗余，写文档还是应尽可能使用书面用语。
口语
我觉得可以先从A到B，这样到了B之后，就可以再去C了。
书面用语
先从A到B，再由B至C。
🎨 一图胜千言
当你发现需要使用大段的文字描述一件事情的逻辑的时候，一张图通常能够帮助你快速理清里面的关系，同时也能避免大量的文字，让读者难以下咽。
养成用图表达的习惯，能用尽用。
我自己通常画图使用的工具是Keynote(没看错，真的很好用，用过都说好)，飞书文档也出一个画板功能，也是非常实用。
举个例子对比，可以直观的看到右图的易读性要远远高于文字描述。
有A、B、C、D、E、F、G七个类，继承关系分别是B、C、D继承自A，E、F继承自B，而G继承自D。而C在实现过程中，引用了D，E引用了F，而F在实现过程中又引用了G。
🎼 善用表格
对于分类/分模块地描述一系列事情，表格是个非常好用的工具。
项目 | PoC | 排期 | 当前进展 |
XXXX | @李云鹏 | xx-xx |
|
YYYY | @李云鹏 | xx-xx |
|
ZZZZ | @李云鹏 | xx-xx |
|
🍱 调排版
文档的核心还是在于内容，但排版应是一个不减分的状态。我并不赞同过分包装、过度形式化，但也反对因噎废食，为此就抛弃任何形式，是否进行一些形式化的动作，本质上还是看对效率是否有所提升。花小部分的时间，来提升大家的阅读效率，是一个典型的可以用小部分时间换大部分收益(二八原则)的事情，个人认为还是比较值得的。
事先声明一下，我并不是专业的设计，了解的设计知识也只是皮毛，所以也可能存在有误的地方，欢迎讨论。
文档不是TXT
人们往往倾向于看到有序的事物(强迫症爽感的来源)，一切安静、平和，但你需要意识到，所有的规整有序，都不是自然发生的，都是有意识的行为。排版好看，是件非常难的事情 ，每个人的审美都有所不同，一千个读者就有一千个哈姆雷特，但反过来说，如果目标只是不难看，那还是相对比较容易的。
排版的目标
读起来规整、有序、高效，不会让人感觉不适
结构化可以体现在排版上，举个例子来感受一下直观差异。
静态分析能做哪些事情呢？可以做诸如强制校验代码遵循编码规范的风格检查，也可以做内存泄漏、循环引用等缺陷检查，还能做限制废弃API的使用、管控敏感API的使用、调用链的隐式影响、以及规范MR的流转流程等等事情。
静态分析能做什么？
- 风格检查 强制校验代码遵循编码规范
- 缺陷检查 内存泄露、循环引用等问题
- 废弃接口 限制废弃API的使用
- 隐私合规 管控敏感API的使用
- 隐式影响 调用链查询
- 流程管控 规范MR流转流程
- ···
显然右侧的结构化更加明显，展现的也更加清晰，读者也更容易关注到重点。
📐 对齐
如果你觉得一个页面不舒服，但是又说不出来哪里不舒服，那大概率就是没对齐
庆幸的是，飞书文档通常会天然的帮你做很多对齐，标题、内容、分栏、列表等等，通常不需要做过多操作，天然就是对齐的。
画图则尤其需要自行注意了，注意多个元素间的对齐关系。多数画图工具都会帮你展示对齐参考线，选中多个元素，也可以使用左右对齐、均匀分布等操作，进行快速批量对齐，非常好用。
养成心中有线，我的眼睛就是尺的习惯。
⚠️ 参考线、对齐操作不是万能的，有时候会起反效果
比如针对不同大小文字，其实就不是真正的对齐(文字两侧的留白会随着字体放大而放大)，这时候往往就需要对齐后再稍微调整。
再比如，不同的icon，如果一味的采用相同大小来对齐，结果也经常是不好看的。
慎用首行缩进
有些人保留了小时候写作文的习惯，会在段落的前方空两个文字的间距完成缩进。但如果你有留心的话，互联网上的文章，已经很少再使用首行缩进了。最早的首行缩进其实是为了节约纸面，这在当下电子场景下，显然已经不用再考虑了，加个空行来明确段落，反而可以使得文章排版更加美观一些。
注意段落大小
考虑一下阅读的场景，主要读者通过手机阅读或者电脑显示器阅读，那显然是不同的，公司文档的阅读场景大多数都会是电脑显示器，而微信公众号的阅读场景，大多数都会是手机屏幕。
我常用的处理方式是在读者常用的屏幕下尽量不超过5行，大段文字真的会非常影响阅读体验。
尝试一下居中以外的对齐方式
除了文档通常默认的左对齐之外，一旦画图，很多人往往会倾向于居中对齐。尝试一下其他对齐方式，左对齐、右对齐，可以让你的表达不再单调。
下图Xcode自动生成的文件，虽然都是文字，但看起来却很舒服，你能找到有多少参考线么？
最后，这并不是说一切皆要对齐，但，打破规则之前必须清楚规则是什么。
⚖️ 对比
不知道你有没有注意到，上面很多例子，其实用到了对比。想要实现有效的对比，那就必须强烈一些，不应该是略有不同，而是截然不同，左右直观对比出二者的差异。飞书一个很好用的功能，那就是分栏。
对比也并非必须是内容对比，不同元素间也可以对比。
我经常会在标题上加上数字序号或者emoji，其实是为了强化标题与正文的对比，飞书的标题设计，让我觉得经常看不见标题在哪里，对比并不强烈，快速翻阅时容易找不到标题。
🎏 重复
标题的粗细样式、列表前的小圆点、缩进、对齐方式、元素大小、间距大小等等任何有意重复的东西。重复项也不一定是完全相同，只是明确存在某种关联的一系列对象(就比如本文标题前方的emoji)。
暂时无法在飞书文档外展示此内容
重复本身，隐含了这些是存在某种关联的一系列对象的暗示，同时会潜意识地带来某种程度上的专业性和权威性，它会让人觉得，有人在为此负责，是一种经过深思熟虑的设计，虽然可能读者本身并没有主观意识到这一点。
👨👩👦 亲密性
所谓亲密性，其实讲的是各个元素之间的关系，刻意将关系更近的内容放在一起，再直白一点就是分组。亲密性的原则是一个非常自然，但有时又注意不到的原则。
举个例子，每小节的内容都会对应小节的标题，这是不言自明的逻辑，这个逻辑的背后其实就是亲密性。当我们进行更复杂的排版，尤其是画图时，亲密性，就显得尤为重要。
还是举上面举过的架构图，将整体分为三层，包含各个子模块，这里的分层逻辑，就是依靠的亲密性。
最后再举一个《写给大家看的设计书》的例子，来直观对比一下应用亲密性之后的效果。
设计排版，往往不是单一地使用某个原则，而是综合的使用多种原则。
🤔 结束语
了解了基本的设计原则，可以在打开一个网页、拿起一瓶水、翻开一本书，思考一下他们都应用了哪些设计原则，你会发现这个世界其实很有意思。但文档最核心的最终还是内容本身，所以大多数时间也都应该放到内容本身上。定主题、立框架，不仅是为了语义上的通顺，更多的是帮助我们理清事情本身。一件事情，自己想得通是一回事，给别人讲得通是一回事，写下来让别人看得通又是另外一回事，我自己的感受是每一步都会促进自己进行更全面地思考。
想把一个逻辑给别人完整讲通其实是一件很难的事情，简单的东西讲复杂不难，难的是复杂的东西讲简单。不知你是否有过这样感觉，当看别人文档、听别人演讲时，感觉这个同学描述的逻辑看起来非常简单，自己一下子就懂了。这个时候，别着急因为自己已经理解了而心有旁骛，感受一下为什么自己可以那么快的理解了，对方的叙事逻辑是怎样的，如果换作自己来讲能否做到这么通俗易懂。
至此，希望本文的内容对你有所帮助，如果觉得还不错，不妨分享给身边其他的同学。
📕 推荐阅读
《金字塔原理》
无需多言，经典中的经典，应该很多人多少都看过一些。
《写给大家看的设计书》
主要讲一些基本的设计原则，篇幅不长，但非常通俗易懂，非常实用，文中的对齐、对比、重复、亲密性这几个原则就是来自这本书，书里面还有更多颜色、字体之类的介绍，这里都没有展开。
读了这本书，最明显的感受就是，当自己感觉有些设计让人觉得不适的时候，能知道不适在哪里。
