Skip to content

飞桨文档写作规范

Chen Long edited this page May 18, 2022 · 2 revisions

文档写作基本原则(红线)

  • 要准确不要错误:

    • 文档内容准确,描述要和产品功能实现完全一致
    • 操作流程需要经过验证,确保可以跑通
    • 用词准确,无错别字,不会误导读者
    • 无死链,确保链接指向的网页/图片一直可用
  • 要完整不要部分:

    • 内容足够完整,无功能点、API或关键步骤信息缺失
    • 保证顺序一致性,文档中的操作流程与实际操作的情况没有差异
  • 要一致不要不同:

    • 保证内容一致性,文档中同一功能在不同位置表述信息一致
    • 内容及时更新,与产品最新推荐功能一致
    • 中英文描述一致,无歧义
  • 要原创不要侵权:

    • 文档中的文字、图片、数据集等信息无版权纠纷,无商用化风险
    • 引用、借鉴段落需标明引用来源,或按需获取授权后使用

一、基本格式规范

格式规范细则可点击下方链接,查看不同内容模块的具体要求说明

参考:ruanyf/document-style-guide: 中文技术文档的写作规范

1.6 表格、图片和代码

  • 表格使用格式准确。表格要与相关正文呼应:

    • 表配文:正文对表格做简要说明。
    • 表就位:表格编排在引文的下方。
    • 文引表:表格之前正文中必须有引文“参见表X-X”。
  • 图形使用格式准确。图形同样需要与相关正文呼应:

    • 图配文:正文对图形做简要说明。
    • 图就位:图形编排再引文的下方。
    • 文引图:图形之前必须有引文“如图X-X所示”。
  • 代码使用格式准确。代码需要与正文呼应:

    • 文引码:代码之前必须有正文对代码综述。
    • 图就位:代码需要在正文的下方。
    • 码配文:代码需要有较为详细的注释,至少是功能点的粒度。

1.7 其他格式要求

  • 向量斜体小写;矩阵大写
  • 公式使用 LaTex 代码,不能使用图片。

二、通用注意事项

逻辑设计

  • 信息组织符合逻辑。例如是否正确归类、符合任务顺序或开发流程等。
  • 文章子标题可以明确反映内容的主题思想。

结构设计

  • 文档每章或每节开始前要有一节“概述”,简要介绍本文的作用,能够快随告诉用户,读完这篇文档,会有什么收获。
  • 较长的段落文字采用了总分结构描述。
  • 在适当的地方使用了列表结构。段落中并列关系的句子,建议使用无序列表;有顺序关系的句子,建议使用有序列表。

内容设计

  • 内容基于用户使用视角设计,而非产品功能角度设计,内容丰富、充分考虑零基础用户的阅读需求。
  • 要保证用户可以轻松准确的读取文档内容,而不需要花费时间去猜想文档所要表达的含义。
  • 文档需关注上下文连贯,与前文后文关联紧密,需要有串联信息。
  • 对于文档第一次出现的专有词汇/新概念,提供了简单的背景知识介绍。
  • 在适当的地方使用了图、表、举例、代码示例等丰富表达,尤其是复杂概念、流程、方案解读建议优先使用图表。
  • 在适当的地方提供了经验技巧、避坑tips等补充信息。
  • 文章内包含了适当的外链。如在结尾添加到API文档的链接,需要的位置补充源码链接。

语句和用词

  • 语句表述清晰、准确、易懂,尽量不要中英文混合表述。
  • 没有在非必要的地方使用“你”、“我”、“他”之类的代词。避免使用您、你之类的代词,可能会对用户情绪产生影响。对于你或您这类可能不好规避的地方,统一使用“你”。
  • 没有错别字、错误标点、死链等问题。
  • 文档中使用的术语与缩略语,符合《术语规范》。
  • 不可使用过于口语化的表达,比如挂死、搞定等。

三、参考模板&注意事项

我们简单的将文档分为2类,一类为原理性的文档,主要是一个特性或功能的介绍、应用场景、概述,都属于描述类信息。另一类为操作类的文档,开发指南中关于某个特性的“使用流程”、“如何操作”的信息。以下给出了这两类文档的参考模板以及相关的注意事项。

3.1 原理类文档

参考模板

# 题目

## 概述
简要介绍本文的作用,能够快随告诉用户,读完这篇文档,会有什么收获。

## 背景简介
说明一下这个文档的背景知识。即在什么场景下,我们遇到了一个什么问题,因此需要有这样一个功能来解决这个问题。

## 如何使用这个基本功能
说明一下,在飞桨框架中,怎么使用这个功能。

## 功能的进阶使用方法
说明一下,这个功能的一些特殊用法/高级用法。

## 功能的原理说明
说明一下 这个功能的原理

# 总结
总结一下本文

注意事项

  • 描述这个应用的场景,在什么情景下解决什么问题。
  • 这个应用的具体功能,能够实现什么。
  • 最好能图文结合,方便用户理解。
  • 通过举例方式讲解复杂内容。

3.2 操作类文档

参考模板

# 题目

## 概述
本篇教程的主题,操作/教程/示例的主体产品是什么,下文中操作的目的是什么

## 步骤/流程
将操作的核心步骤在概述进行总结,可以整理为类似目录的多级小标题

## 环境准备/前置条件(可选)
在执行操作前需要准备的内容,需要逐条说明如何准备/如何检验是否已准备完成;考虑尽可能多的前置条件

## 主要操作步骤
将每一步操作的具体方式和操作结果准确呈现,每一步内可以包含
  (1)本步骤操作的说明
  (2)操作指令/方式,代码/脚本/指令/图示/关键字
  (3)操作结果,文字/图示
  (4)操作中可能遇到的问题
  (5)与本步骤相关的更详细信息的链接指引

# 总结
总结一下本文

注意事项

  • 操作环节的划分和标题是按照用户视角的任务来呈现。推荐使用谓语+宾语的格式
  • 每个任务或子任务的操作步骤不超过9个。
  • 一个步骤如果比较复杂,可以考虑分解成多个步骤,然后以总分的方式来写。
    • 总:一句话写出这一步骤是做什么。推荐句式:动作+目的(总述)
    • 分:写出具体的每个步骤操作。
  • 明确步骤执行的地点,避免用户迷失。如在操作系统的根目录下执行。
  • 对于不是必须做的步骤,在步骤前加(可选 )。
  • 每个步骤都给出了证明步骤成功的结果。
  • 各个步骤若涉及到一些说明、注意信息,需要就近在各个步骤前后说明,以引起重视。如某步骤可能会引起问题,需要说明。
  • 若某个步骤操作的时间比较长,超过1分钟,需要在步骤增加时长的说明,让用户心理有数。否则用户可能因为等待时间过长,不确定操作是否出错。

术语规范