目录:
一图看懂文档写作流程规范编辑
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 一直维护下去。
以上分享的是一个完整的技术文档从零到有的过程。日常工作中,有时不需要从头开始,而只是对原有文档的增删修改,那就可以省去一些相应的环节。
修改文档的时候:发挥主观能动性,调整和优化内容,让组织结构更清晰,从而在不改变原意的基础上更好地传达意思,使技术文档更易读。