编写规范

这里我将描述文档编写规范格式，将从一下几个方面进行详细的介绍。

1. 标题
2. 文本
3. 段落
4. 数字
5. 标点符号
6. 文档体系

标题

定义文档中标题的使用规范。

层级

• 一级标题：文章的主标题
• 二级标题：文章的主干章节标题
• 三级标题：章节下的分支标题
• 四级标题：属三级标题内的分支标题

示例

# 一级标题
## 二级标题
### 三级标题
#### 四级别标题

原则

• 一级标题，全文仅能有一个一级标题，在本站中每篇文章的一级标题不能改手动设置，一级标题的值为正文头部的YAML 或 TOML 格式的数据元中 title 字段的值，标题使用不能跨级。

示例：标题跨级，缺少二级标题

# 一级标题
### 三级标题

• 二级标题，为文档的主干章节的标题，二级标题会出现在文档右侧的章节导航中,因此每个二级标题应当是一个完整的内容单元，同时在使用二级标题时应当避免出现孤立标题。

示例：下方的文章结构中，二级标题 A 中只有包含一个三级标题，不推荐此写法，完全可以省略三级标题。

## 二级标题 A
### 三级标题
## 二级标题 B

• 下级标题不能与上级标题重复。

示例：下方结构中，三级标题与二级标题同名，应当避免。

## 概述
### 概述

• 谨慎使用4级标题，应尽量避免出现，保持层级简洁，若三级标题下有并列性的内容，建议使用项目列表。

示例：下方有两个文章结构，结构二比结构一好，后者更适合内容较长的篇幅。

结构一
### 三级标题
#### 四级标题A
#### 四级标题B
#### 四级标题C
结构二
### 三级标题
**（1）A**
**（2）B**
**（3）C**

文本

字间距

全角中文字符与半角英文字符之间，应当有一个半角空格。

错误：本手册将指导您如何使用Swoft框架。
正确：本手册将指导您如何使用 Swoft 框架。

全角中文字符与半角阿拉伯数字之间，有没有加空格都可以，但是要保证风格统一不能两种风格混杂。

英文单位若不翻译，单位与前方的数字不留空格

错误：这是一部 4 GB 运存的手机
正确：这是一部 4GB 运存的手机

半角字符与全角标点符号之间不留空格。

写作风格

1. 尽量使用主动语态，避免被动语态。

   错误：假如此软件尚未被安装。
   正确：假如尚未安装这个软件
   

2. 不使用非正式语言风格

   错误：这个框架简直爽翻天。
   正确：使用这个框架使人感到愉悦。
   

3. 不要使用生僻字、文言文的词语

   错误：这是唯二的方法。
   正确：这是仅有的两种方法。
   

4. 请用对 的、地、得

   形容词+的+名词
   副词+地+动词
   动词+得+副词
   

5. 使用代词（如其、该、此、这等词）时必须明确代词的指向，避免歧义。

6. 名词前不要使用过多的形容词

7. 不包含任何标点符号的句子，或以逗号分隔的句子，长度尽量保持在20字以内，30～39个字的句子语义必须明确，任何情况下都不接受多于40个字的句子。

8. 只有一种意思的句子尽量使用肯定句表达，不使用否定句。

   错误：请确保没有开启省电模式。
   正确：请确保省电模式已关闭。
   

9. 避免使用双重否定句

   错误：没有删除权限的用户，不能删除此文件。
   正确：用户必须拥有删除权限，才能删除此文件。
   

英文处理

英文原文如果使用了复数形式，翻译时应将其还原成单数形式。

英文：information stored in random access memory (RAMs)
中文：存储在随机存储器（RAM）里的信息

英文缩写可以使用半角圆点.表示缩写，例如 U.S.A、Apple,Inc.

英文书名或电影名该用中文表达时，双引号应改为书名号。

第一次出现的英文词汇，应在括号中给出中文标注，后续再次出现时，直接使用缩写。

段落

段落原则

• 一个段落只能有一个主题，或一个中心句子。
• 段落的中心句子方段首，对全段内容做概述。后面的陈述句为核心句服务。
• 段落长度避免过长，最佳长度应小于等于四行，一定不能超过七行。
• 段落的句子预期要使用陈述和肯定预期，避免使用感叹语气。
• 段落开头不要流出空白字符。
• 书写时每个段落应该用空行隔开。

引用

引用第三方内容时，应注明出处。

引用内容。–引用出处

如果时全篇转载，请在全文开头显著位置注明作者和出处，若原文有链接地址，应给出原文链接。

本文转自 百度

数值

半角数字

所有数字一律使用英文半角形式，不得使用中文全角形式。

千分号

数值为千位以上时，应添加千分号 ,。

示例： 实际到账金额为 RMB1,000,000。

对于4～6位的数值，千分号可用可不用，比如1000和1,000都可以接受。而对于6位以上的数值，则必须带千分号。

对于多位的小数点则应按照小数点后开始从左向右添加千分号例如5.235,345。

货币

货币应为阿拉伯数字，并且在数字前方写出货币符号或者在货币后方给出中文货币名。

¥998
$230
456美元

数值范围

表示数值范围时，用~连接，对于带有单位或百分号时，~符号两边的数值都要加上单位或百分号，不能只加一个。

错误：100～130KG
正确：100KG~130KG

变化程度

数字的增加使用“增加了”、“增加到”。“了”表示增量，“到”表示定量。

内存增加到之前的两倍（指的是过去为一，现在为二）。
内存比之前增加了两倍（指的是过去为一，现在为三）。

数字的减少与增加规则同理，应使用“降低了”、“降低到”。值得注意的是不能使用“降低N倍“或”减少N倍“的表示法，要用”降低百分之几“或”减少百分之几“，因为减少或降低一倍表示的意思是数值原来为一百，现在等于零。

标点符号

标点符号原则

• 中文语句的标点符号应全都采用全角符号，保证视觉统一。
• 如果证据为英文，则使用英文半角符号。
• 句号、问号、叹号、逗号、顿号、分号和冒号都不得出现在行首。

句号

中文语句中的结尾处应该使用全角句号。。

句子末尾有括号时，句号应加在括号之外。

逗号

逗号，表示句子内部的停顿。

注意避免出现“一逗到底”的情况，即整个段落除了结尾句号，全部使用逗号停顿。

顿号

中文句子内部的并列词语之间使用全角顿号分割、，即使并列词是英文也是如此。

英文句子中的并词之间应使用半角逗号 , 分隔。

分号

分号；表示复句内并列分句之间的停顿。

引号

引用时，应该使用全角引号“”，注意前后引号不同。

引号内部还需使用引号时，外层使用双引号，内层使用但引号‘’，注意都是全角的，前后但引号不同。

圆括号

补充性说明的内容，应使用圆括号（）括起来，括号前后不加空格。

冒号

全角冒号：常用在需要解释的词语后面，引出解释说明。

表示时间时，应使用过半角冒号 :。

省略号

省略号……表示语句未完成、或语气不连续。它占用两个汉子空间，包含六个省略点，不要使用。。。或 ... 等非标准形式。同时省略号不应该与“等”这个词一起使用。

感叹号

编写文档时应当使用平静的语气叙述，尽量避免使用感叹号！，不得多个感叹号连用，例如！！！。

破折号

破折号————一般用于进一步解释说明。

破折号应占用两个汉子位。如果破折号本身只占用一个汉子位置时，前后应该空出一个半角空格。

连接号

连接号-主要用于两个词语的连接。

以下场景中连接号只占用一个半角字符位。

• 两个名词的连接
• 图表的编号

以下场景中连接号应该使用波浪号～，占一个全角字符位。

• 数值范围

注意，波浪号前后两个值都应加上单位。波浪号也可以用汉字“至”代替。

文档体系

文档文件名

文档的文件名不得有空格，不能使用全角字符。因此不能使用中文做文件名。

文件名只建议使用小写字母，不建议有大写。

文件名包含多个单词时，单词之间使用连词线-连接。

内容深度

此文档的核心作用是作为操作手册来使用，不需要过深的介绍概念原理。

主要写作方向应当是以框架本身为核心，介绍框架如何使用，应当避免涉及过多的框架以外的内容，保持文档内容简洁不混乱。

其他的知识点内容应当以引用的方式向读者说明。关于更深层次的文档，应当分离出来独立进行编写。

举例子来说，操作手册就等同于一台设备的说明书，主要是介绍设备如何操作、运行、维护等内容，而不会涉及到介绍这台设备是如何制造的，用了什么材料，如何加工的，使用的什么电路板和芯片。

文档片段示例

在使用本框架时，我们会假设您已经对 Swoole，有了一定的基础，我们不会解释关于 Swoole 的部分。

内容广度

在每一个篇章中，应当是一个独立的知识点介绍，不应当重复描述其他章节的内容，如有必要可给出所需章节的链接指向。

每个篇章中，应当尽可能详细的对本篇文章内容做解释说明，对于文档中所提到的相关操作必须解释清楚。

我们的目标是编写一份通俗易懂，且能详细的展现框架的各项功能使用方式、注意事项等内容。

通常情况下我们每篇文章的内容都应当符合以下核心：

• 解释一个功能具体的使用方式
• 把功能描述清楚，而不是假设大家对这个功能很熟悉
• 示例应尽可能的简单易懂
• 链接到其它文档，而不是在这里重新解释概念
• 不要解释过程，是只告诉你最终结果
• 介绍此功能的使用场景，包括不适用的场景

内容结构示例

## 基本功能介绍
1. 用清晰简短的语句描述功能作用
2. 描述清楚使用此功能的相关注意事项
## 功能的相关配置选项
与本功能相关的所有操作选项等尽可能完整的介绍清楚
## 使用场景
1. 介绍适合或不适合使用本功能的场景
2. 若本功能的不适用场景有替代方案时应当介绍
## 简单的示例
提供使用本功能的简单示例
## 额外的上下文
可以写一些额外的补充性说明内容

具体示例请查看 文档示例

文档编写指导说明

目录结构

网站的所有文档内容都在 content/documents/ 目录下，其中 v1 对应的是文档1.0，v2 对应的是文档2.0，每个文档内的 _index.md 就是文档的默认首页。

文档2.0的一级目录大纲在 config/_default/menus.toml 文件内以 [[v2]] 标记标注的，name 是一级目录的标题；weight 是一级目录的排序数值，数值越大越靠后，若一级目录是单独可点击的没有子目录则使用 url 字段，若有子目录则使用 identifier 字段标记一级目录的 ID，此字段不可重复。

# v2文档一级菜单
[[v2]]
  name = "框架概述" #目录的名字
  weight = 1 #目录的排序，序号越小越靠前
  url = "/documents/v2/" #无子目录时，点击直接跳转的地址
[[v2]]
  name = "开发基础" #目录名字
  weight = 10   #目录的排序
  identifier = "dev-basis" #本级目录的 ID 标志，全局不可重复。

文档的二级菜单是通过具体的文章内的标记元确定的。

注意 子目录的存放位置与一级导航的 ID 标记无任何关联，但是为了方便日后维护，因此将以一级目录的 ID 值为文件夹，在文件夹内存放子目录的内容。

文档标记元

每篇文档的头部都会有一些标记元，可以是 YAML 格式或 TOML 格式的配置项，下面会对配置项做一个解释说明。下面会以 TOML 格式为准解释相关标记元素。

+++ #TOML标记符号，标记符号必须在第一行，前面不能有空格、空行。
title = "使用案例" #一级标题，若没有使用 linktitle 字段则目录上的名字和此字段名一致。
linktitle = "案例" #目录标题
toc = true #是否显示文档右侧的小目录
type = "docs" #不许更改
date = "2018-09-19" #文档创建日期
lastmod = "2018-09-20" #最后修改日期
[menu.v2] #目录标记
  parent = "dev-basis" #所属上级目录，值为一级目录的 identifier 字段
  weight = 1 #一级目录下的排序

weight = 1 #文档的导航器，此顺序建议和 menu 下的 weight 顺序保持一致，此选项将影响页面上的上一页和下一页的导航。
+++

特别说明，若是在文档中的 _index.md 进行设置，则以下字段有特别的含义。

+++
linktitle = "v2文档" #字段值将会在文档列表中显示为文档的标题
summary = "文档描述" #字段值是文档的描述字段，将会显示在文档列表中
weight = 1 #如果有多份文档，则此字段影响本文档的排序顺序
+++

关于更多的标记元素请查阅 hugo文档 和 academic模板 文档。