技术文档写作流程规范

编辑
  • 文档创建者:susie
  • 浏览次数:1689次
  • 编辑次数:6次
  • 最近更新:susie 于 2019-05-27
  • 一图看懂文档写作流程规范

    文档写作流程规范-用户.png

    1. 准备阶段

    • 明确文档需求

    • 明确文档受众

    • 界定文档范围

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

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

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

    2. 调研阶段

    1)  产品的需求文档。

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

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

    3. 文档架构

    在创建文档的时候,直接选择对应的「模板」自动生成「文档大纲」。

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

    分为四个选项,根据实际情况,选择对应的模板,点击「确定」即可,如下图所示:

    4. 文档写作

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

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

    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. 审阅修改

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

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

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

    6. 文档交付

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



    附件列表


    主题: 下架文档
    标签: 暂无标签 编辑/添加标签
    如果您认为本文档还有待完善,请编辑

    文档内容仅供参考,如果你需要获取更多帮助,付费/准付费客户请咨询帆软技术支持
    关于技术问题,您还可以前往帆软社区,点击顶部搜索框旁边的提问按钮
    若您还有其他非技术类问题,可以联系帆软传说哥(qq:1745114201

    此页面有帮助吗?只是浏览 [ 去社区提问 ]