目录:
一图看懂文档写作流程规范编辑
1.Preparation 准备阶段
明确文档需求
明确文档受众
界定文档范围
明确文档需求:要了解为什么要写这篇文档,写这篇文档是为了达到什么目的。
明确文档受众:面对普通用户。
界定文档范围:思考并确定这篇文档需要覆盖哪些内容或模块,以及不会涉及哪些内容。
2.Research 调研阶段
1) 产品的需求文档。
2)尽力搜集与所写文档相关的各种资料。
对于软件类的产品文档,还需要自己操作一遍,从而对操作步骤有一个直观的理解,获得文档写作的一手资料。
3.Organization 文档架构
在创建文档的时候,直接选择对应的「模板」自动生成「文档大纲」。
选取模板自动生成文档大纲
分为四个选项,根据实际情况,选择对应的模板,点击「确定」即可,如下图所示:
4.Writing 文档写作
这时候再将相应的内容准确地填到文档架构中。
但是写作的时候也需要一些好的写作习惯:良好的语言功底、规范的语法、得体的措辞、正确的标点。
4.1 原则
从用户角度出发
一目了然(是什么?为什么?)
专业(措辞简洁、内容完整、含义精准)
内在有逻辑,外表有颜值
4.2 标题
标题概括翻译章节的中心内容
标题简洁扼要、涵义明确
标题的长度,不要超过 10 个字
4.3 段落
段落的中心句子放在段首,对全段内容进行概述。后面陈述的句子为核心句服务。
4.4 文本
4.4.1 句子
句子要使用简单句和并列句,避免使用复合句。
句子要避免使用长句。
句子要避免歧义结构
4.4.2 表格
举例时,用合理、完整的模拟数据,而不是无意义、残缺的测试数据
4.4.3 超链接
正文中被引用的内容在其他地方已经详细描述,这时可以使用内容引用(超链接)。
引用内容为 | 引用统一表达为 |
---|---|
一篇文档 | 请参见 标题文字 |
一篇文档里的某个章节 | 请参见 标题文字 中第2.2节的描述 |
4.4.4 语言
精简语句
完整、直接得阐述信息
用词精准完整
基本用词要规范
4.5 排版技巧
基本标点规范
字间距:所有的中文字和半形的英文、数字、符号、链接之间应该插入空格
4.6 图示标准
请参见 文档图示标注规范 。
不过初次编辑文档的用户也不需要担心,如果写作的初稿有些粗糙,有需要修改的小细节,「官方审核人员」会在审核的时候进行修改的。
5.Revision 审阅修改
写完文档第一稿后,一般都需要进一步修改完善。从下面两个方面进行修改:
Technical Review:从技术层面看文档中的描述是否正确有效
Language Review:从语言层面看文档中的表达是否简洁得体、图片是否正常显示、超链接是否正常跳转
6.Delivery 文档交付
等文档修改完成后,点击发布即可,「官方审核人员」会进行审核,审核通过后,所有人可见。