如何写好一篇文档?

🌄 前言

什么是好的文档？在我看来，不减分地表达清楚作者的意图，即是一个不错的文档，

从作者角度上讲，能够让读者快速、清晰理解作者要表达的内容。
从读者角度上讲，读者能够快速、清晰地了解到自己想要了解的内容。

那如何写好文档呢，先抛观点。

自顶向下地结构化表达 + 一点点的排版 = 一篇不错的文档

Talk is cheap. 先抛出自己写过的一些文档，你可以大概瞄一眼，如果觉得还算认可，就可以继续阅读，如果不认可，就也节约时间了。

🧑💻 工作

以我常写的技术方案为例，除去方案本身的设计时间，大概时间占比如下

定主题 10%
立框架 20%

填内容 60%
调排版 10%

除大家都熟练的填内容之外，其他部分比如排版，在刚开始时肯定会需要更多的时间，但用不了多久就不会再花更多时间，唯手熟尔。最后还是要先强调一下，每个人都有自己的写作习惯，不用刻意模仿，没有意义。写这篇文档的原因也只是把自己的经验分享出来，未必都对，仅供参考，欢迎讨论。

🎯 定主题

定主题这件事情其实很简单，写一篇文档一定是有所目的，这里想强调的是，写文档的时候要反复回看自己的主题是什么，偏离主题的讨论应当适当简化，这样才能让文档不那么冗余，别人读起来才会比较舒服。定主题的重点不在主题本身，而是有主题这件事情，即主题是什么不重要，重要的是存在主题&忠于主题。

文档的所有内容，都应当是为主题服务的。

这件事情看似非常简单，但在实操过程中却非常难以做到的。比如描写如何从北京到上海的技术方案，重点在于什么时间去、有哪些交通方式、有哪些优劣势，常见的错误就是写着写着，却花了大量的篇幅去讲飞机是怎么组成的、高铁是哪里制造的。

并不是说不能写这些东西，而是这些东西并不切题，读起来很容易有一种东一榔头、西一棒槌的感觉，如果真的觉得有必要说明一下，那更好的方式是一笔带过或者附加链接的形式。

🍢 立框架

文档并不会像长篇书籍一样拥有复杂的框架，通常目录就可以看做文档的主框架。但一个文档未必只有一个框架，恰恰相反，通常都会有多个框架。立框架不止是写全文之前，写每一具体的部分也可以先立框架，再写内容，有些框架是显式展现给读者的，有些框架则是作者仅用以写作的。

我以常写技术方案为例

框架		作用
主框架	文档	以目录为中心，统领全文的行文逻辑
次框架	技术方案	以方案架构图/流程图为中心，统领技术方案的描述逻辑
次框架	产品方案	以PRD为中心，统领用户视角下的产品逻辑

立框架有以下几个好处

帮助自己梳理思路，防止遗漏要点
确保内容不会偏题，抓得住重点
抽象地看框架，更容易将事情调理顺
读者更容易理解作者的思考逻辑

框架的重点在于思考逻辑，而不是表达细节

举一个我实际改过的例子，文档背景大概是一些任务偶尔会存在网络抖动，进而导致任务失败，这些失败通常是可以通过重试解决，故我们希望建立一个自动重试机制，来避免用户受到这部分失败的影响。

项目背景
稳定性问题分类
- 可直接重试解决
- 重试不可解决，需手动处理
稳定性问题分类解决方案
- 重试可解决
  - 机器问题被杀、环境依赖问题
  - 网络问题
- 重试不可解决，需手动处理的方案构思
  - 文件数过大导致任务超时
  - 规则代码不当导致crash（数组越界等）
  - 规则throw异常
数据指标
具体实施技术方案
项目目标
里程碑

主要有以下几个问题

内容维度
- 文档缺乏数据支撑，只知道有这种(网络抖动)情况存在，但是不知道占比多少，也没法预估收益多少
- 非重试能解决的问题显然不是这个方案要重点解决的问题，但却占据了相当的篇幅，偏离了主题
- 标题不够精简，包含了太多实现细节，"不像标题"，不了解背景的人也很难理解这些细节到底什么意思
- 对于技术方案整体没有一个完整的描述，所有的描述都在指向细节，读者很难有全局视角一以贯之
逻辑维度

这个逻辑并不是定死的，参杂了一些个人习惯，但目标是一定的，即下一节所讲的内容要符合读者的心理预期，不让人感觉到太过跳脱。不必追求逻辑的精妙，越简单的逻辑，反而越容易理解。
- 解决方案和技术方案本质上是一件事情，但却被拆成了两个小节，造成了内容的不连贯
- 目标应该紧随背景，只有讲明白目标是什么，读者才能跟着作者的思路实现对应的目标，以及提出相关建议
  
  目标应该是事先定好的，而不是总结而来的，这样才能使得文章整体是自顶向下的。
- 逻辑上，先讲背景，让大家理解了背景，再讲目标，然后拆解目标，为目标提供数据支撑，再讲实现方案，最后定一些关键指标来评估效果。这样的逻辑上是相对比较顺的，阅读、理解也更容易。
美观维度
- 太多的细节，以及不像标题的标题，排版起来也不太美观

经过一番修改，对比前后

修改前

项目背景
稳定性问题分类
- 可直接重试解决
- 重试不可解决，需手动处理
稳定性问题分类解决方案
- 重试可解决
  - 机器问题被杀、环境依赖问题
  - 网络问题
- 重试不可解决，需手动处理的方案构思
  - 文件数过大导致任务超时
  - 规则代码不当导致crash（数组越界等）
  - 规则throw异常
数据指标
具体实施技术方案
项目目标
里程碑

修改后

背景
目标
前期调研
- 数据统计
- 问题分类
- 流程现状
技术方案
- 概览
- 重试机制
- 数据指标
里程碑
相关文档

技术方案是研发同学最常要写的文档，你会发现上面这个模板几乎适用于各种技术文档，技术方案这类文档恰好也是模板化最显著的一类，按照大的框架来写，至少可以保证不会犯错。其实无论是不是技术文档，在叙事逻辑上，无论是文档、PPT、视频各种各样的形式，形式的变化其实都不影响叙事逻辑，自顶向下的结构化表达，是读者最容易快速理解的方式。

这就是我对框架的理解，框架只是思考叙事的结构，真的只是框架就好，不需要多么惊艳，只要能帮助作者、读者理清逻辑、不犯错即可。如果你细心，看下本文的目标结构，其实也是非常简单的。

能套模板了，为什么还会占用20%的时间？

答案其实隐含在前文里了，一个文档通常都会有多个框架，这里只是讲了主框架，在填内容的过程中，每个小节通常都可以有自己的框架，这是我认为立框架能占到20%的时间的主要原因。

🥗 填内容

结构化不应只体现在框架上，而是方方面面。

🛠️ 常见要素

🌄 背景

无论是写文档，还是写PPT，背景都是非常重要的环节，大家往往会低估背景描述的价值。写背景时，必须站在一个没有相关知识背景的读者的角度去描述。

最常见的错误就是，作者觉得自己的方案理所应当，所以背景就简单一两句话概括。绝大多数时候，你觉得一两句话能阐述清楚的背景，大概率是因为你具备充分的背景知识，对于一个不了解现状的读者来说，显然是无法理解的。精简、直观甚至巧妙的背景描述、案例列举，让读者能够快速了解并理解背景，是带动读者"入局"的关键。

作者和读者之间，通常会存在比较显著的信息差，而作为作者，需要有意识地减少这种信息差。

如果读者都不了解背景是什么，那他对你的想法/方案大概率是无法理解的，很容易不知所云。遇到比较多在评审时，总会有人提出一些看似角度刁钻的问题，作者不得不反复阐述问题背景。出现这种情形，归根结底是背景没有真正阐述清楚。加大在背景上的投入，绝对是一件非常值得的事情。

🎯 目标

让读者了解完背景之后，抽象地给自己以下要阐述的内容定下核心诉求，显式地强调出来，而不是让读者去猜、去感受，这样有助于读者了解这篇文档到底是要干什么。只有明确了目标，读者才能真正基于目标来了解后续内容的巧妙，或评估后续内容的合理性，提出有用的建议。带着目标阅读，可以显著地提高阅读效率。

🛠️ 方案

如何写好一个方案，我的答案依旧是自顶向下的结构化表达，先立框架，再填内容。

我通常会先画一个架构图，来梳理我以下要讲的内容的框架。

出自抖音iOS基础质量团队丨技术发展全景 (长期规划)

当然也有同学可能并不赞同这种图，觉得一眼看过去并不知所云，我依然推荐的原因如下

内在原因 (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	xxx
YYYY YYYY	@李云鹏	xx-xx	xxx xxx
ZZZZ	@李云鹏	xx-xx	xxx xxx

项目

PoC

排期

当前进展

XXXX

@李云鹏

xx-xx

YYYY

YYYY

@李云鹏

xx-xx

ZZZZ

@李云鹏

xx-xx

🍱 调排版

文档的核心还是在于内容，但排版应是一个不减分的状态。我并不赞同过分包装、过度形式化，但也反对因噎废食，为此就抛弃任何形式，是否进行一些形式化的动作，本质上还是看对效率是否有所提升。花小部分的时间，来提升大家的阅读效率，是一个典型的可以用小部分时间换大部分收益(二八原则)的事情，个人认为还是比较值得的。

事先声明一下，我并不是专业的设计，了解的设计知识也只是皮毛，所以也可能存在有误的地方，欢迎讨论。

文档不是TXT

人们往往倾向于看到有序的事物(强迫症爽感的来源)，一切安静、平和，但你需要意识到，所有的规整有序，都不是自然发生的，都是有意识的行为。排版好看，是件非常难的事情，每个人的审美都有所不同，一千个读者就有一千个哈姆雷特，但反过来说，如果目标只是不难看，那还是相对比较容易的。

排版的目标

读起来规整、有序、高效，不会让人感觉不适

结构化可以体现在排版上，举个例子来感受一下直观差异。

静态分析能做哪些事情呢？可以做诸如强制校验代码遵循编码规范的风格检查，也可以做内存泄漏、循环引用等缺陷检查，还能做限制废弃API的使用、管控敏感API的使用、调用链的隐式影响、以及规范MR的流转流程等等事情。

静态分析能做什么？

风格检查 强制校验代码遵循编码规范
缺陷检查 内存泄露、循环引用等问题
废弃接口 限制废弃API的使用
隐私合规 管控敏感API的使用
隐式影响 调用链查询
流程管控 规范MR流转流程
···

显然右侧的结构化更加明显，展现的也更加清晰，读者也更容易关注到重点。

📐 对齐

如果你觉得一个页面不舒服，但是又说不出来哪里不舒服，那大概率就是没对齐

庆幸的是，飞书文档通常会天然的帮你做很多对齐，标题、内容、分栏、列表等等，通常不需要做过多操作，天然就是对齐的。

画图则尤其需要自行注意了，注意多个元素间的对齐关系。多数画图工具都会帮你展示对齐参考线，选中多个元素，也可以使用左右对齐、均匀分布等操作，进行快速批量对齐，非常好用。

养成心中有线，我的眼睛就是尺的习惯。

⚠️ 参考线、对齐操作不是万能的，有时候会起反效果

比如针对不同大小文字，其实就不是真正的对齐(文字两侧的留白会随着字体放大而放大)，这时候往往就需要对齐后再稍微调整。

再比如，不同的icon，如果一味的采用相同大小来对齐，结果也经常是不好看的。

慎用首行缩进

有些人保留了小时候写作文的习惯，会在段落的前方空两个文字的间距完成缩进。但如果你有留心的话，互联网上的文章，已经很少再使用首行缩进了。最早的首行缩进其实是为了节约纸面，这在当下电子场景下，显然已经不用再考虑了，加个空行来明确段落，反而可以使得文章排版更加美观一些。

注意段落大小

考虑一下阅读的场景，主要读者通过手机阅读或者电脑显示器阅读，那显然是不同的，公司文档的阅读场景大多数都会是电脑显示器，而微信公众号的阅读场景，大多数都会是手机屏幕。

我常用的处理方式是在读者常用的屏幕下尽量不超过5行，大段文字真的会非常影响阅读体验。

尝试一下居中以外的对齐方式

除了文档通常默认的左对齐之外，一旦画图，很多人往往会倾向于居中对齐。尝试一下其他对齐方式，左对齐、右对齐，可以让你的表达不再单调。

下图Xcode自动生成的文件，虽然都是文字，但看起来却很舒服，你能找到有多少参考线么？

最后，这并不是说一切皆要对齐，但，打破规则之前必须清楚规则是什么。

⚖️ 对比

不知道你有没有注意到，上面很多例子，其实用到了对比。想要实现有效的对比，那就必须强烈一些，不应该是略有不同，而是截然不同，左右直观对比出二者的差异。飞书一个很好用的功能，那就是分栏。

对比也并非必须是内容对比，不同元素间也可以对比。

我经常会在标题上加上数字序号或者emoji，其实是为了强化标题与正文的对比，飞书的标题设计，让我觉得经常看不见标题在哪里，对比并不强烈，快速翻阅时容易找不到标题。

🎏 重复

标题的粗细样式、列表前的小圆点、缩进、对齐方式、元素大小、间距大小等等任何有意重复的东西。重复项也不一定是完全相同，只是明确存在某种关联的一系列对象(就比如本文标题前方的emoji)。

暂时无法在飞书文档外展示此内容

重复本身，隐含了这些是存在某种关联的一系列对象的暗示，同时会潜意识地带来某种程度上的专业性和权威性，它会让人觉得，有人在为此负责，是一种经过深思熟虑的设计，虽然可能读者本身并没有主观意识到这一点。

👨👩👦 亲密性

所谓亲密性，其实讲的是各个元素之间的关系，刻意将关系更近的内容放在一起，再直白一点就是分组。亲密性的原则是一个非常自然，但有时又注意不到的原则。

举个例子，每小节的内容都会对应小节的标题，这是不言自明的逻辑，这个逻辑的背后其实就是亲密性。当我们进行更复杂的排版，尤其是画图时，亲密性，就显得尤为重要。

还是举上面举过的架构图，将整体分为三层，包含各个子模块，这里的分层逻辑，就是依靠的亲密性。

最后再举一个《写给大家看的设计书》的例子，来直观对比一下应用亲密性之后的效果。

设计排版，往往不是单一地使用某个原则，而是综合的使用多种原则。

🤔 结束语

了解了基本的设计原则，可以在打开一个网页、拿起一瓶水、翻开一本书，思考一下他们都应用了哪些设计原则，你会发现这个世界其实很有意思。但文档最核心的最终还是内容本身，所以大多数时间也都应该放到内容本身上。定主题、立框架，不仅是为了语义上的通顺，更多的是帮助我们理清事情本身。一件事情，自己想得通是一回事，给别人讲得通是一回事，写下来让别人看得通又是另外一回事，我自己的感受是每一步都会促进自己进行更全面地思考。

想把一个逻辑给别人完整讲通其实是一件很难的事情，简单的东西讲复杂不难，难的是复杂的东西讲简单。不知你是否有过这样感觉，当看别人文档、听别人演讲时，感觉这个同学描述的逻辑看起来非常简单，自己一下子就懂了。这个时候，别着急因为自己已经理解了而心有旁骛，感受一下为什么自己可以那么快的理解了，对方的叙事逻辑是怎样的，如果换作自己来讲能否做到这么通俗易懂。

至此，希望本文的内容对你有所帮助，如果觉得还不错，不妨分享给身边其他的同学。