社区投稿风格指南

本指南为 Cloud Native Community 投稿技术文档的编写提供了一套风格指南规范。

本指南为 Cloud Native Community 投稿技术文档的编写提供了一套风格指南规范（属于 云原生社区投稿 Review 标准 中对格式的详细要求）。主要目的为：

  • 提高中文文案可读性
  • 统一文档风格，保证社区投稿对外输出风格一致
  • 避免不同的文档作者对同一问题反复作出决策，降低与文档相关的沟通成本

文件头

所有投稿文章都需要在投稿文件的头部添加文件头（文件头前后使用三个短横线“-”），例如：

---
title: "文章标题"
date: 2020-06-09T06:00:00+08:00
description: "对本文的摘要或者描述。"
author: "[Heng Lonng](https://github.com/lonng)"
categories: ["Kubernetes"]
tags: ["Kubernetes", "源码分析", "kube-apiserver"]
type: "post"
avatar: "/images/profile/jimmysong.jpg"
profile: "作者简介。"
---

其中：

  • title: 表示投稿的标题，例如：社区投稿风格指南。
  • date: 表示投稿的时间，使用 RFC3999 格式，例如：2020-06-09T06:00:00+08:00。
  • description: 表示对投稿内容的简要描述，尽量控制在 100 字以内，例如：本指南为 Cloud Native Community 投稿技术文档的编写提供了一套风格指南规范。。
  • author: 表示投稿作者，使用 Markdown 格式，例如：[Heng Lonng](https://github.com/lonng)。
  • image：博客的 banner，比例为 16:9，如 images/blog/k8s-client-go-banner.png。
  • categories: 是用于分类技术类别的，例如“Kubernetes”、“Istio”等。
  • tags: 表示投稿的 TAG，使用数组的形式，例如：["社区", "风格", "投稿"]。
  • type: 表示投稿的类型，例如：guide，如果是投稿，这个 type 的值使用 post 即可，其他类型的页面再选择对应的 type，这个 type 的值实际是指定页面布局。
    • guide
    • post
    • project
    • team
    • service
    • none
  • avatar : 表示作者头像，请放置正方形头像到/images/profile目录下，例如： /images/profile/jimmysong.jpg。
  • profile: 表示作者简介，例如：云原生布道师，ServiceMesher 社区联合创始人，CNCF Ambassador，热衷开源和分享。。

注意：以上为添加博客时必须指定的所有 header，对于其他页面只需要设置 title、description、type 即可，有的页面可能需要其他 header 配置，请参考对应的页面已有文章。

标题

技术文档中使用标题最多不超过四级。标题从一级开始递增使用，禁止跳级使用。例如：一级标题下面不能直接使用三级标题；二级标题下面不能直接使用四级标题。

  • 一级标题：即文章标题（一级已出现在 Title 中，所以正文不应该再包含一级标题）
  • 二级标题：文章正文部分的标题
  • 三级标题：二级标题下面一级的小标题
  • 四级标题：三级标题下面某一方面的小标题

为避免出现过于复杂的章节，若无特殊需要，不建议使用四级标题。如果三级标题下有并列性的内容，建议使用列表 (list) 代替四级标题。

标题的描述

技术文档中的标题包括但不限于以下几种描述：

  • 名词词组，如“…概述”、“背景”、“原理”
  • 主题词+动词，如“Docker 安装”、“Kubernetes 部署”
  • 动词+主题词，如“配置 MySQL 数据库”
  • 定语+主题词，如“A 工具的安装”，“A 工具的架构”
  • 介词+定语+主题词，如“对机器配置的要求”

标题描述的设计并无严格的模板，只要遵循以下几个原则即可：

  • 标题能够概括反映本章节的中心内容。
  • 标题简洁扼要、涵义明确。
  • 同级别的标题尽量使用相同的结构。
  • 标题描述操作任务时建议使用“动词+主题词”结构，不建议使用名词词组。

使用标题的注意事项

技术文档中使用标题主要有以下几个注意事项：

  • 下级标题禁止重复上一级标题的内容。
  • 禁止标题以标点符号（如句号、冒号、问号等）结尾
  • 禁止在标题中解释缩略语。
  • 标题与标题之间一定要有引导介绍性的句子。例如，一级标题和二级标题之间应有引言，- 二级标题和三级标题之间应有正文内容。
  • 标题要避免孤立编号（即同级标题只有一个），正文不要有孤立的三级标题和四级标题。
  • 项目列表（包括无序和有序列表）是最小编号单位，因此项目列表下禁止嵌套任何级别的标题。

段落

段落是正文部分的基本构成单元之一，由多个句子组成段落写作要求如下：

  • 段落之间使用一个空行隔开。
  • 段落开头不需要缩进，顶格开始即可。
  • 一个段落只能有一个主题，或一个中心句子。
  • 一个段落里避免只有一个句子。如果句子很长，要避免“一逗到底”的情况，合理断句。
  • 一个段落的长度建议在 50～200 字之间，尽量不要超过 250 字。（Word 里统计字数）
  • 段落的句子语气应该使用陈述和肯定语气，避免使用感叹语气。
  • 对于技术描述类主题，应考虑先图表，后句子的原则，不要单一的使用段落来陈述主题。
  • 段落的中心句子建议放在段首，对全段内容进行概述。后面陈述的句子为核心句服务。

文档内容元素

缩写词

建议使用全写形式，比如 Prometheus 不要使用 P8s，Kubernetes 不要使用 K8s。

空白符号

空白符号包括空格、空行等，其中空格分为半角空格和全角空格。

  • 空格

    • 禁止使用全角空格，一律使用半角空格。
    • 中文字符（包括汉字和中文标点符号）和中文字符之间禁止空半角空格。
    • 中文标点符号前、后禁止空格。
    • 对于英文字符和阿拉伯数字，应使用半角空格包围，以下情况例外：
      • 位于句首时，左边空格省略。
      • 其右侧为全角标点时，右边空格省略。
    • 除表示缩进、列表级别、代码块中固有空格外，禁止连续出现两个及以上的半角空格。
    • 禁止使用 Tab（制表符）替换空格。

  • 空行

    • 不同段落间必须使用一个空行隔开。
    • 插入表格、图片等元素时，插入的语句前后需有一个空行。
    • 不同排版格式之间使用一个空行隔开，如标题后的正文，正文中的代码块等。
    • 禁止连续出现两个及以上的空行。

Tab 和空格的使用

技术文档中经常使用 Tab 键和空格键进行缩进和对齐。由于在不同的编辑器里 Tab 的默认长度可能不一致，用 Tab 键设置缩进可能导致格式混乱。如果使用空格键设置缩进，则用任何编辑器打开文档都会显示一样的对齐效果。

因此，投稿技术文档中必须使用空格键而不用 Tab 键进行缩进或对齐。

【建议】如使用 Visual Studio Code 等编辑器编写文档，可以统一设置一个 Tab 等于四个半角空格。

列表

当有 3 项或更多重要信息需要展示时，纵向列表是最清晰且吸引眼球的方式。但如果项目少于 3 项且无需特别强调，将其直接放在句子中通常效果更好。

也可以创建多级嵌套列表，在某一级别下另起一行，缩进四个空格即可开始更低级别的列表。

无序列表和有序列表

技术文档中的列表分为有序列表 (ordered list) 和无序列表 (unordered list) 两种。一般而言，当列表项之间的顺序不重要时，使用无序列表；当各项之间的顺序很重要时，使用有序列表。

【无序列表示例】 目前 Prometheus 中相关组件：

  • Prometheus Server：用于收集和存储时间序列数据。
  • Client 代码库：用于定制程序中需要的 Metric。
  • Alertmanager：用于实现报警机制。

【有序列表示例】 解决步骤：

  1. 编辑数据源文件。
  2. 手动创建所有的表。
  3. 设置参数跳过检查。

有序列表的使用场景较少。当列表项的内容是以下几种时，应该使用有序列表。

  • 必须按顺序操作的步骤（最常用）
  • 需要进行排名的多项内容
  • 需要在下文进行引用的规则或其它信息（比如下文需要引用该列表的第 3 项时可以说“规则 3”）

【重要原则】除非顺序很重要，否则不要使用有序列表！

代码块

投稿文档使用 Markdown 语言编写，插入及高亮代码块的常用方式有两种

  • 用“`”包裹语句中的某个参数名或关键字。

  • 用“```”包裹多行代码。如需高亮代码块，只需在第一行之后加上相应的语法名称。

    pwd

插入代码块应遵循以下规范

  • 代码块前后必须加上一行空行。
  • 代码块要注意缩进。

标点符号

技术文档中的标点符号极易用错，文档作者必须牢记规范，保证文档的美观性和可读性。

中文标点使用

使用中文标点符号应遵循以下规范。

  • 中文语句中的标点符号一律使用全角形式（即中文输入法下的标点符号），不得使用半角形式（即英文输入法下的标点符号）。
  • 中文全角标点符号两旁禁止空半角空格。示例：
    • 【错误示例】如果 CPU 设有限额 （从 Kubernetes 指定的上限） ，则需要手动调整。
    • 【正确示例】如果 CPU 设有限额（从 Kubernetes 指定的上限），则需要手动调整。

中英文混排格式

中文技术文档中不仅会出现中文标点，也可能出现英文标点，因此在中英文混排时应着重注意中英文标点的使用。

中英文混排时使用标点符号应遵循以下规范。

  • 括号里全为英文时使用半角括号，并在括号前后各空一个半角空格，括号和括号内的英文之间不需要空格。
  • 括号里既有中文又有英文（即只要括号内包含任何中文）时使用全角括号，括号前后不空格。
  • 全角标点与英文或数字之间不加空格。

常用中文标点符号

技术文档中容易用错的标点符号主要有：句号、逗号、顿号、分号、冒号、引号、括号、书名号、连接号、破折号、省略号。下文介绍了它们的使用规范。

句号

句号的形式为“。”，常用于陈述句末尾的停顿。

句号表示一个句子的意思已经完整，技术文档中应善用句号切分语意，帮助用户理清逻辑。

逗号

逗号的形式为“，”，表示句子内部的一般性停顿。

逗号虽然没有特殊、专门的意义，使用也最普遍，但是不能滥用。技术文档中不要出现“一‘逗’到底”的错误，即整个段落除了段落结尾外，全部停顿都使用逗号。

顿号

顿号的形式为“、”，表示句子内部并列词语之间的停顿。 中文中表述三者或三者以上的并列情况时，必须用顿号，而不用逗号表示。

分号

分号的形式为“；”，表示复句内部并列分句之间的停顿。一般情况下，并列分句有三句或超过三句时，建议使用分号表示停顿。

冒号

冒号的形式为“：”。在技术文档中常用在需要解释的词语后边，表示引出解释和说明。

引号

引号分为直角引号和弯引号。直角引号为「」，弯引号有双引号和单引号两种形式。投稿技术文档中统一使用弯引号，禁止使用直角引号。

本节只讨论弯引号使用的一些规范，下文中使用的“引号”含义即为“弯引号”含义。

  • 引号里面还要用引号时，外面一层用双引号，里面一层用单引号。
  • 技术文档出现报错信息、特定操作或名称、缩略语提示、特殊名词等时，建议使用引号。

括号

括号的常用形式包括圆括号“()”、方括号“[ ]”、方头括号“【】”、尖括号“<>”（也称单书名号）以及花括号“{}”。除 markdown 特有的格式需求（如用 []() 引用链接）外，投稿文档正文中常出现的是圆括号、尖括号和花括号。

书名号

书名号的形式为双书名号“《》”。书名、篇名、报纸名、刊物名等，用书名号标示。英文手册名称用双引号或斜体表示，不用书名号标示。

连接号

连接号的常见形式为“—”，占一个字的位置。连接号还有另外四种形式，即长横“——”（占两个字的位置）、半字线“–”（占半个字的位置）、短划线“-”（占1/3个字的位置）和浪纹“~”（占一个字的位置）。

破折号

破折号的形式为“——”，占两个字的位置。技术文档中破折号常用于引出注释和说明部分。

省略号

中文省略号的形式为“……”，有六个小圆点，占两个字的位置。一般而言，中文语句中禁止使用三个小圆点“…”（英文省略号），必须使用六个小圆点“……”。