001 | 文章vs工程文档

工程文档101攻略

我曾酷爱文章. 续过人家的小说, 编过自己的故事, 琢磨过用字, 也自诩高明地打过笔仗.

后来我写代码了. 代码无情, 有结构但没故事, 有语法但没偏好. 代码的完成意味着一个过程的结束, 而非拉开一场演出的帷幕. 这些都跟写文章写小说差之千里.

生活中我逐渐远离了写作; 我想, 除了入了行的人, 大家可能也都远离了超过5分钟的文字. 随着表达工具的延展, 文字不再具有往日的冲击力. 如果能通过图片在0.1秒内抓住你的眼球, 文章可能需要你阅读至少5分钟.

码字的年岁见长, 工作中逐渐形成另一套写作的天地: 既要严谨的逻辑, 也得在情理中折服众人. 这中, 除了对文字的权衡, 也有对观众的把握, 还要对结构深思, 配上那0.1秒的冲击(图片), 最后需要作者现场的表演来完成文档的使命.

这就是表达工程思想的必经之路: 文档. 可能是工程设计文档, 可能是项目计划文档, 可能是教程文档…总而言之, 能把文档写得漂亮高效, 整个人都觉得神清气爽.

抛砖引玉, 今天我们聊聊写文档的结构.

平时我都在英文环境下做文档, 那么就以此为大纲, 然后加以解释.

假如说, 今天我要写一份教程文档, 譬如一个项目完结了, 我们要记录它的架构, 方便后人理解.

---

Overview 概括

这部分, 一定要简略: 不需要看你文档的人, 看完这一段可以离开. 需要看文档的人, 让他知道你到底要表达什么.

1/ 简短描述这个文档的意义! (很多人会忘记这一点, 并不是所有人都能立刻明白你的文档作用为何)

2/ 简短描述这个项目是什么

(举例) This document covers the technical design of the chat feature on WeChat. The chat feature allows two or more users to send text messages over the internet instantly.

Background 背景资料

1/ 介绍项目的背景, 加一些需要补充概括的内容. 上面概括里面提到的大家需要进一步理解的细节, 在这里指出.

2/ 外部链接: 这里是你提供外部链接的最好时机. 本文档有些无法涵盖的内容, 将大家指引到别的地方阅读. (提早指出, 免得读者看完整篇文档, 才发现找不到需要的东西)

3/ 读者要求: 指出, 谁是可以看这个文档的人? 是工程师团队, 还是项目经理, 还是设计师团队, 还是用户? 如果错的读者看到这里, 大约知道自己该停了. 同时, 所有人读到这里, 也应该明白这是什么文档, 而不会再后期要求你改正文档的规格或表达.

Text chat is a known feature on QQ since 2000, but WeChat aims for a different user group and simplifies the user experience. For the overall WeChat feature list, please refer to this [link].

This document will cover an overview of the system as well as backend components in depth. The engineering group can continue reading the ‘Components’ section, and other teams can start the discussion in the Architecture section.

Glossary 文档词汇

如果你的文档里, 为了方便表达而使用许多特定的缩写, 最好在这里提前给读者提示. 特别是当不同组的人看到你的文档, 一眼看上去满篇的XYZ缩写, 一定需要找到XYZ的意义.

再着,这里也是给读者一个预防针: 如果你完全不明白文档词汇里面说的是什么, 那么也许, 你(读者)并不适合继续阅读.

XYZ: WeChat Xtremely Yo Zone Service

Architecture 基本架构

- 在这里, 应该是开始了文档最想要表达的内容. 如果是工程项目文档, 通常大家会画流程图来表达架构, 或者是请求/响应的流程, 或者是数据的流水. 对, 用图片, 0.1秒抓住眼球!

- 这里也等于是技术环节的'概括'. 我们需要在这个部分言简意赅的表达, 让读者鸟瞰整个布局, 有需要的话, 甚至可以简化流程图.

- 这里要说明, 虽言简意赅, 但并不是过度简化; 需要讨论的具体细节, 会在下一个篇章展开

- 很多时候, 读者可能看到这里就停了. 或许他已经了解的项目的全部, 或许他并不是工程师也不需要继续往下看, 或者这里就明显出了大问题, 他找你讨论去了.

Please see this API workflow diagram:

The detailed engineering components will be explained in the next section.

Components 详尽部件

- 很明显, 这个环节, 把上面的流程图, 一个个部分拆开来解释清楚

- 在流程图里面的点, 最好一定都要有对应的解释

- 具体需要多少细节, 就要参考这个文档到底是用来干什么的? 读者是简单看看理解就好, 还是需要学会整个架构然后参与项目?

ComponentAlice

…

ComponentBob

…

FAQ 常见问题

- 如题

- 我会把项目里遇到的问题,或者缺乏思考的问题, 总结在此

• Who still uses WeChat today? Answer: pretty much everybody.

---

这里, 是上面用到的模板

### Overview 概括
### Background 背景资料
### Glossary 文档词汇
### Architecture 基本架构
### Components 详尽部件
### FAQ 常见问题

• 技术文档与平日文章之最大不同: 重点内容, 用最简练的语句, 最前排表达清楚.

• 技术文档与平日文章之最大共通: 从观众的角度, 在适当的时刻, 送上最得当的内容.

不论是那种文字格式, 都在试图表达一些主观思想, 并且带动人思考. 而工程文档的形成, 很多时候是相互讨论的结果, 因此, 充分为读者做好心理准备, 提供足够的工具和背景, 变成工程文档最必不可少的环节.