飞桨文档写作规范

飞桨文档写作规范

基本原则

• 文档内容一定是准确的，不能有跑不通、错别字、死链等问题。
• 要保证用户可以轻松准确的读取文档内容，而不需要花费时间去猜想文档所要表达的含义。
• 文档开始前要有一节“概述”，简要介绍本文的作用，能够快随告诉用户，读完这篇文档，会有什么收获。
• 主语不用“我们，您，用户，开发者”等，使用第二人称“你”。

一、基本格式规范

• 1.1 标题
• 1.2 文本
• 1.3 段落
• 1.4 数值
• 1.5 标点符号

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

二、其他注意事项

操作类文档

• 代码段必须确保可运行，并需要有适当的注释。
• 一个步骤如果比较复杂，可以考虑分解成多个步骤，然后以总分的方式来写。
  • 总：一句话写出这一步骤是做什么。推荐句式：动作+目的（总述）
  • 分：写出具体的每个步骤操作。
• 明确步骤执行的地点，避免用户迷失。如在操作系统的根目录下执行。
• 对于不是必须做的步骤，在步骤前加（可选 ）。
• 各个步骤若涉及到一些说明、注意信息，需要就近在各个步骤前后说明，以引起重视。如某步骤可能会引起问题，需要说明。
• 若某个步骤操作的时间比较长，超过1分钟，需要在步骤增加时长的说明，让用户心理有数。否则用户可能因为等待时间过长，不确定操作是否出错。

术语规范

• 深度学习术语表
• 飞桨产品名称规范表[TBD]