社区投稿风格指南

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

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

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

文件头

所有投稿文章都需要在投稿文件的头部添加文件头(文件头前后使用三个短横线“-”),例如:

---
title: "社区投稿风格指南"
date: 2020-06-09T06:00:00+08:00
description: "本指南为 Cloud Native Community 投稿技术文档的编写提供了一套风格指南规范。"
author: "[Heng Lonng](https://github.com/lonng)"
categories: ["指南"]
tags: ["社区", "风格", "投稿"]
type: "guide"
avatar: "/images/profile/jimmysong.jpg"
profile: "蚂蚁金服云原生布道师,ServiceMesher 社区联合创始人,CNCF Ambassador,热衷开源和分享。"
---

其中:

  • title: 表示投稿的标题,例如:社区投稿风格指南
  • date: 表示投稿的时间,使用 RFC3999 格式,例如:2020-06-09T06:00:00+08:00
  • description: 表示对投稿内容的简要描述,尽量控制在 100 字以内,例如:本指南为 Cloud Native Community 投稿技术文档的编写提供了一套风格指南规范。
  • author: 表示投稿作者,使用 Markdown 格式,例如:[Heng Lonng](https://github.com/lonng)
  • 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,热衷开源和分享。

标题

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

  • 一级标题:即文章标题(一级已出现在 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 语言编写,插入及高亮代码块的常用方式有两种 - 用“”包裹语句中的某个参数名或关键字。 - 用“``”包裹多行代码。如需高亮代码块,只需在第一行之后加上相应的语法名称。

```shell
pwd
```

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

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

标点符号

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

中文标点使用

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

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

中英文混排格式

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

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

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

常用中文标点符号

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

句号

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

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

逗号

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

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

顿号

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

分号

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

冒号

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

引号

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

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

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

括号

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

书名号

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

连接号

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

破折号

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

省略号

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