飞桨文档写作规范 - PaddlePaddle/docs GitHub Wiki

文档写作基本原则（红线）

  • 要准确不要错误：

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

  • 要完整不要部分：

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

  • 要一致不要不同：

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

  • 要原创不要侵权：

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

一、基本格式规范

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

1.1 标题

1.2 文本

1.3 段落

1.4 数值

1.5 标点符号

参考：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分钟，需要在步骤增加时长的说明，让用户心理有数。否则用户可能因为等待时间过长，不确定操作是否出错。

术语规范