技术文档写作流程规范

  • 文档创建者:susie
  • 编辑次数:12次
  • 最近更新:susie 于 2019-10-18
  • 一图看懂文档写作流程规范

    1571365986924633.png

    1. 需求分析

    • 明确文档需求

    • 明确文档受众

    • 界定文档范围

    • 信息收集

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

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

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

    进行信息收集:1)  产品的需求文档。

                         2)尽力搜集与所写文档相关的各种资料。

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

    2. 结构化写作模式

    WX20191018-104042@2x.png

    2.1 任务(怎么做)

    1571368987582512.png

    2.2 概念(是什么)

    1571368262796184.png

    2.3 故障解决(FAQ)

    1571368298794025.png

    注:术语表和参考两类创建的比较少,不提供专门的模板

    2.4 选取模板自动生成文档结构

    在创建文档的时候,根据文档类型,直接选择选择对应的「Topic 类型」的模板自动生成「文档结构」,如下图所示:

    WX20191018-110551@2x.png

    3. 文档写作

    这时候再将相应的内容准确地填到文档架构中。

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

    3.1 原则

    从用户角度出发

    • 一目了然(是什么?为什么?)

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

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

    3.2 标题

    • 标题概括翻译章节的中心内容

    • 标题简洁扼要、涵义明确

    • 标题的长度,不要超过 10 个字

    3.3 段落

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

    3.4 文本

    3.4.1 句子

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

    • 句子要避免使用长句。

    • 句子要避免歧义结构

    3.4.2 表格

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

    3.4.3 超链接

    正文中被引用的内容在其他地方已经详细描述,这时可以使用内容引用(超链接)。

    引用内容为

    引用统一表达为

    一篇文档请参见 标题文字
    一篇文档里的某个章节请参见 标题文字 中第2.2节的描述

    3.4.4 语言

    3.5 排版技巧

    • 基本标点规范

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

    3.6 图示标准

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

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

    4. 审阅修改

    写完文档第一稿后,一般都需要进一步修改完善。从下面两个方面进行修改:

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

    • 从语言层面看文档中的表达是否简洁得体、图片是否正常显示、超链接是否正常跳转、是否有错别字等等

    5. 文档发布

    等文档修改完成后,点击发布即可,「官方审核人员」会进行审核,审核通过后,所有人可见。

    6. 维护

    文档发布后,我们会根据文档解决率、文档缺陷率、评论,对文档进行不断完善。


    附件列表


    主题: 下架文档
    • 有帮助
    • 没帮助
    • 只是浏览