编写规范

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

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

标题

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

层级

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

示例

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

原则

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

示例:标题跨级,缺少二级标题

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

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

## 二级标题 A
### 三级标题
## 二级标题 B
  • 下级标题不能与上级标题重复。

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

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

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

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

文本

字间距

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

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

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

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

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

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

写作风格

  1. 尽量使用主动语态,避免被动语态。
错误:假如此软件尚未被安装。
正确:假如尚未安装这个软件
  1. 不使用非正式语言风格
错误:这个框架简直爽翻天。
正确:使用这个框架使人感到愉悦。
  1. 不要使用生僻字、文言文的词语
错误:这是唯二的方法。
正确:这是仅有的两种方法。
  1. 请用对
形容词+的+名词
副词+地+动词
动词+得+副词
  1. 使用代词(如等词)时必须明确代词的指向,避免歧义。

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

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

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

错误:请确保没有开启省电模式。
正确:请确保省电模式已关闭。
  1. 避免使用双重否定句
错误:没有删除权限的用户,不能删除此文件。
正确:用户必须拥有删除权限,才能删除此文件。

英文处理

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

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

英文缩写可以使用半角圆点.表示缩写,例如 U.S.AApple,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模板 文档。

上一页
下一页