1.Preparation 准备阶段

• 明确文档需求

• 明确文档受众

• 界定文档范围

明确文档需求：要了解为什么要写这篇文档，写这篇文档是为了达到什么目的。

明确文档受众：面对普通用户。

界定文档范围：思考并确定这篇文档需要覆盖哪些内容或模块，以及不会涉及哪些内容。

2.Research 调研阶段

1)  首先产品的需求文档。

2）采用最有效的方法尽力搜集与所写文档相关的各种资料。

对于软件类的产品文档，还需要 Technical Writer 自己操作一遍，从而对操作步骤有一个直观的理解，获得文档写作的一手资料。

3.Organization 文档架构

对于常见的产品使用指南，一般按照安装或使用的顺序进行组织；对于其它一些非指南类的文档，也应遵循一定的顺序或逻辑。

这里我们可以在创建文档的时候，直接选择对应的「模板」自动生成「文档大纲」。

选取模板自动生成文档大纲

从模板创建文档，分为四个选项，根据实际情况，选择对应的模板，点击「确定」即可，如下图所示：

4.Writing 文档写作

如果做好了前几步的工作，写作将变得非常简单，你只需把相应的内容准确地填到文档架构中。

但是写作的时候也需要一些好的写作习惯：良好的语言功底、规范的语法、得体的措辞、正确的标点。

4.1 原则

从用户角度出发

• 一目了然（是什么？为什么？）

• 专业（措辞简洁、内容完整、含义精准）

• 内在有逻辑，外表有颜值

4.2 标题

• 样式

• 标题的设计

• 标题设计注意事项

• 文档分类

4.3 段落

段落的中心句子放在段首，对全段内容进行概述。后面陈述的句子为核心句服务。

4.4 文本

4.4.1 句子

• 句子要使用简单句和并列句，避免使用复合句。

• 句子要避免使用长句。

• 句子要避免歧义结构

4.4.2 表格

举例时，用合理、完整的模拟数据，而不是无意义、残缺的测试数据

4.4.3语言

• 精简语句

• 完整、直接得阐述信息

• 用词精准完整

• 基本用词要规范

4.5 排版技巧

• 基本标点规范

• 字间距：所有的中文字和半形的英文、数字、符号、链接之间应该插入空格

4.6 图示标准

请参见 文档图示标注规范。

不过初次编辑文档的用户也不需要担心，如果写作的初稿有些粗糙，有需要修改的小细节，「官方审核人员」会在审核的时候进行修改的。

5.Revision 审阅修改

写完文档第一稿后，一般都需要进一步修改完善。这里的 Revision 指的是 review 之后的修改，所以这一步也可以叫作：Review & Revision。

那么需要谁来 review 呢？技术文档通常需要请其他小伙伴进行两种 review，即：

• Technical Review：从技术层面看文档中的描述是否正确有效

• Language Review：从语言层面看文档中的表达是否简洁得体

收到 reviewer 的反馈之后，Technical Writer 需要及时作出判断和修改，有不明确的地方需和 reviewer 讨论确定。

改完之后，再请 reviewer 看一下。如果又发现了新的问题，那么还需要再次修改。这个 review - revise 的过程可能会反复几次，很正常。

当然，在请他人 review 之前，Technical Writer 也可以先自己 review 一遍，尽量避免低级错误，不浪费他人的时间。

6.Delivery 文档交付

等文档定稿之后，就可以在平台上发布了，一般很容易操作。不同的公司的文档发布平台也会不一样，Technical Writer 使用的写作工具也不一样。

文档发布之后，并不代表着结束。根据我的工作经历，即便是已经发布的文档，也依然有可能存在问题，无论是大公司还是小公司的文档。

例如：未发现的文字错误、失效的链接、与最新的产品已不匹配的描述和步骤等。Technical Writer 需要及时跟进产品动态，以便及时更新文档。

Afterword

写技术文档不是一劳永逸的，只要产品在更新，就需要 Technical Writer 一直维护下去。

以上分享的是一个完整的技术文档从零到有的过程。日常工作中，有时不需要从头开始，而只是对原有文档的增删修改，那就可以省去一些相应的环节。

修改文档的时候：发挥主观能动性，调整和优化内容，让组织结构更清晰，从而在不改变原意的基础上更好地传达意思，使技术文档更易读。