Skip to content

style-guide.md

Latest commit

 

History

History
executable file
·
160 lines (109 loc) · 7.5 KB

style-guide.md

File metadata and controls

executable file
·
160 lines (109 loc) · 7.5 KB

文档写作风格与规范

欢迎您加入 KWDB 文档小组，与我们一起建设更加易用、用户友好的 KWDB 文档。为提升文档的风格一致性和易读性，避免不同作者在编写文档时因风格不一致导致的文档差异，KWDB 提供了文档写作风格和规范指南。该指南在语言风格、文档主题、标题、图片、表格、代码、告警和提示、标点等方面做出了明确的风格说明或者建议。请您参考此指南编辑 KWDB 技术文档。

语言风格

用户为中心

语言表达需以用户为中心。在撰写文档时，需考虑不同读者的水平，尽量从技术普及的角度介绍步骤或者操作，表达应循序渐进，避免前后内容跨度较大，造成用户理解困难。

简洁清晰

文档语言应当简洁、清晰。建议您在完成文档初稿后，通读全文，在不影响意思及表达效果的前提下，尽量保持句子的简短和清晰，删除文档中没有明显作用的内容和表达。具体要求如下：

  • 避免冗余和重复。
  • 逻辑清晰、前后保持一致性。
  • 使用行业通用术语、避免使用行话、俚语及网络流行语。
  • 使用人称代词、指示代词时，要明确所指，不造成歧义。
  • 尽量使用主动类型的祈使句，少使用被动语句。

客观恰当

  • 应使用客观的语言表达技术文档内容，技术内容应遵循产品的实际特性和功能，避免功能夸大、不切实际的表述。
  • 不使用模糊、主观性的词，例如，非常、大量、极大、数倍，尽量使用具体的数据来表达程度和变化。
  • 不能包含敏感信息、暴力、种族歧视或性别歧视的内容。
  • 提交原创内容，内容不应侵犯他人知识产权。

语态和语句

  • 尽量使用主动语态的祈使句，不使用被动语态。
  • 对于用户、读者等的称呼全文人称需一致，避免针对同一目标对象使用多种称谓。

文档结构主题

KWDB 文档主要包含三种类型的主题。建议您在编辑文档时，了解处理内容所属的主题类型，然后基于相应的类型要求撰写相应的文档内容。

介绍型主题

介绍型主题用于回答“是什么?” 的问题，它们提供了用户在成功使用产品或界面之前必须知道的背景信息、流程等，例如原理介绍、使用场景、使用流程。

介绍型主题包括下列内容:

  • 概念介绍
  • 功能背景、支持情况
  • 使用流程（如何使用及相应步骤）
  • 约束及注意事项

任务型主题

任务型主题是任务为中心，介绍任务的前提条件、步骤、验证、注意事项等，它们提供一步一步的指导，使用户能够执行任务。

任务型主题包括下列内容:

  • 简短的描述：一个引导性的段落，介绍是什么场景或者关于什么的任务执行。
  • 任务主体：任务主题的主体。它可能包括:
    • 先决条件
    • 上下文
    • 步骤
    • 结果
    • 例子

参考型主题

该主题主要涉及参数说明、代码示例、功能或者命令的介绍和说明等内容。例如，在撰写任务主题时，有时步骤中会涉及到一些配置的介绍和解释，但这些配置内容非常多且有不同场景的要求，在步骤中全部介绍会导致内容可读性差，这时您可以将相关内容放到参考主题中，其它地方要使用这些参考时，引用过去即可。

该主题包括下列内容:

  • 简短的描述：一个引导性的句子，介绍是功能、参数或者命令是什么及作用。
  • 使用或者说明
  • 示例

标题

  • 标题命名
    • 标题要简洁、清晰且能够概括反映章节的中心内容。
    • 操作类的文档使用“动词+主题词”，例如，“开通权限”、“启动服务”。
    • 相同级别、相同类型的标题结构保持一致。
    • 标题不使用标点符号结尾。
  • 标题层级：
    • 单个文档只能有一个 H1 标题。标题从一级开始递增使用，禁止跨级使用标题。
    • 建议文档标题最多不超过四级。

图片

KWDB 文档插入图片时应遵循以下规范：

  • 图片必须清晰可辨识。
  • 只能插入 .png（推荐）和 .jpg 格式的图片。
  • 请使用字母、数字、下划线命名图片，且图片命名应有意义，便于后续查找。
  • 图片统一存放到文档同级目录下的 static 文件夹中。
  • 图片应贴合文档内容，对文档起辅助作用，避免使用与文档无关联、或者关联不大的图片。

表格

  • 所有表格都必须有表头描述。
  • 含义相同的表头描述，应保持表头描述统一，例如，“字段解释”、“字段说明”。“字段描述”这种表头描述，全文尽量采用并保持一种。
  • 表格内容应尽量简练，文字表述风格保持一致。
  • 不出现空白单元格。若单元格无内容或者不适用，填写“无”或者“不适用”。
  • 列宽调整
    • 使用 <div style="width:200px">文本内容</div> HTML 标记语言调整列宽。
  • SQL 语句或操作符中的管道符号
    • 使用 &#124; 代替 SQL 语句或操作符中的管道符号

代码块

KWDB 文档的代码块使用 Markdown 语言的两种代码插入和高亮方式：

  • 使用代码符号（`）包括裹语句或者命令中某个参数名或关键字。代码符号中的内容会渲染为灰色底色。例如，version。

  • 使用代码块符号（```）包裹多行代码。VuePress 使用 Prism 为 Markdown 中的代码块实现语法高亮。如需高亮代码块，你只需在第一个代码块符号（```）之后加上相应语法名称。

    CREATE DATABASE <db_name>;

  • 代码行高亮。Vuepress 支持代码行高亮，你只需在第一个代码代码块符号（```）之后待高亮的行数即可。

    export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}

除了单行以外，你也可指定多行，行数区间，或是两者都指定。

  • 行数区间: 例如 {5-8}, {3-10}, {10-17}
  • 多个单行: 例如 {4,7,9}
  • 行数区间与多个单行: 例如 {4,7-13,16,23-27,40}

告警和提示

告警和提示内容在技术文档中起强调作用。KWDB 文档中的告警和提示包含说明 、注意、提示和详细信息。具体信息，参见 VuePress 官方文档。

该三种类型注意和说明的格式一致。以 说明为例，格式如下：

::: warning 说明 这是一个说明。 :::

链接

KWDB 文档的链接遵循 Markdown 引用链接语法和格式，需要注意的是链接的描述内容需要有意义，便于后续的搜索和优化。您在编辑完文档后，应检查所有链接的有效性，避免无效链接。

标点

KWDB 文档中文标点符号遵循以下规范:

  • 中文语句中标点符号一律使用全角形式（中文输入法下的标点符号），不使用半角形式（英文输入法下的标点符号）。
  • 中文全角标点符号前后禁止留有空半角空格。

文件命名

  • 文件必须使用 .md 后缀。
  • 文件名应能体现内容核心信息。例如，deploy-kaiwudb.md。
  • 文件名不宜过长，建议不超过 4 个英文单词。
  • 文件名须统一使用小写字母。
  • 当文件名由多个英文单词组成时，单词中间应使用连接线（-）隔开。