文档编写规范

1 标题与层级

  • 一级标题 #：文章标题
  • 二级标题 ##：文章内容的一级标题（例： ## 1 概述 ）
  • 三级标题 ###：文章内容的二级标题（例： ### 1.1 适用版本 ）
  • 四级标题 ####：文章内容的三级标题（例： #### 1.1.1 软件版本 ）

层级原则：

  1. 一级标题下，不能直接出现三级标题。

  2. 标题要避免孤立编号（即同级标题只有一个）

  3. 下级标题不重复上一级标题的名字

  4. 谨慎使用四级标题，尽量避免出现，保持层级的简单，防止出现过于复杂的章节。如果三级标题下有并列性的内容，建议只使用项目列表（Item list）

注意：文章内的一、二、三级标题需按照上述示例的格式标记标题样式、序号。
注意：文章标题、文章内的一、二、三级标题不可使用加粗字体。
英文文档的文章标题、文章内的一、二、三级标题单词首字母大写。

2 字间距

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

    错误：本文介绍如何快速启动Windows系统。

正确：本文介绍如何快速启动 Windows 系统。

  2. 全角中文字符与半角阿拉伯数字之间，有没有半角空格都可，但必须保证风格统一（建议增加一个半角空格）。半角的百分号，视同阿拉伯数字。

    正确：2011 年 5 月 15 日，我订购了 5 台笔记本电脑与 10 台平板电脑。

正确：今年我国经济增长率是 6.5%。

  3. 英文单位若不翻译，单位前的阿拉伯数字与单位符号之间，留出一个半角空格。

    例1：一部容量为 16 GB 的智能手机

  4. 半角英文字符和半角阿拉伯数字，与全角标点符号之间不留空格。

    正确：他的电脑是 MacBook Air。

错误：他的电脑是 MacBook Air 。

  5. 链接之间增加空格，加粗、斜体、高亮文本前后加空格。

    ```markdown 正确：请 提交一个 issue 并分配给相关同事。

    正确：修复了一个 内存泄露 问题，该问题由 someone 在 版本 v0.1.1 中引入。

    正确：测试文本，这是测试。

3 标点符号与数字

标点符号与数字使用原则：

  1. 中文语句的标点符号，均采取全角符号，与全角文字保持视觉的一致。

  2. 如果整句为英文，则该句使用英文/半角标点。

  3. 句号、问号、叹号、逗号、顿号、分号和冒号不得出现在一行之首。

  4. 阿拉伯数字一律使用半角形式，不得使用全角形式。

  5. 数值为千位以上，应添加千分号（半角逗号）。

  6. 数值范围：

    • 表示数值范围时，用 ～ 连接。

    • 带有单位或百分号时，两个数字建议都要加上单位或百分号。

4 句子

  1. 避免使用长句。

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

   正确：本产品适用于多种体系结构。无论是由一台服务器（单一节点结构），还是由多台服务器（并行处理结构）进行动作控制，均可以使用本产品。

   错误：本产品适用于从由一台服务器进行动作控制的单一节点结构到由多台服务器进行动作控制的并行处理程序结构等多种体系结构。

  1. 尽量使用简单句和并列举，避免使用复合句。

    并列句：他昨天生病了，没有参加会议。

复合句：那个昨天生病的人没有参加会议。

  2. 同一个意思，尽量使用肯定句表达，不使用否定句表达。

    正确：请确认装置的电源已关闭。

错误：请确认没有接通装置的电源。

  3. 避免使用双重否定句。

    ```markdown 正确：用户必须拥有删除权限，才能删除此文件。

    错误：没有删除权限的用户，不能删除此文件。

5 界面、控件描述

建议描述原则：

  • 界面，包括主页、提示框、信息框等，均使用 【】。

    示例：打开【开始】界面

  • 需要单击或者长按的，包括文字按钮、图标等，均使用 【】，其后可选加对应的图标。

  • 界面中的文字均使用 “ ”。

  • 路径表达方式： 

    “首页 > 设置 > 偏好 > 时间”

6 写作风格

  1. 尽量使用主动语态。

     正确：假如尚未安装这个软件，

 错误：假如此软件尚未被安装，

  2. 不适用非正式的语言风格。

     正确：无法参加本次活动，我深感遗憾。

 错误：Lady Gaga 的演唱会真是酷毙了，从没看过这么给力的表演！！！

  3. 不使用冷僻、生造或者文言文的词语，而要使用现代汉语的常用表达方式。

     正确：这是仅有的两种快速启动的方法。

 错误：这是唯二的快速启动的方法。

  4. 用对“的”、“地”、“得”。

     她露出了开心的笑容。
 （形容词＋的＋名词）

 她开心地笑了。
 （副词＋地＋动词）

 她笑得很开心。
 （动词＋得＋副词）

  5. 使用代词时（比如“其”、“该”、“此”、“这”等词），必须明确指代的内容，保证只有一个含义。

     正确：从管理系统可以监视两个系统：中继系统和受中继系统直接控制的分配系统。

 错误：从管理系统可以监视中继系统和受其直接控制的分配系统。

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

     正确：此设备必须在技师的指导下使用，且指导技师必须接受过由本公司举办的正式设备培训。

 错误：此设备的使用必须在接受过本公司举办的正式的设备培训的技师的指导下进行。

7 英文处理

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

     英文：⋯information stored in random access memory (RAMs)⋯

 中文：……存储在随机存取存储器（RAM）里的信息……

  2. 外文缩写可以使用半角圆点(.)表示缩写。

     U.S.A.
 Apple, Inc.

  3. 表示中文时，英文省略号（⋯）应改为中文省略号（……）。

     英文：5 minutes later⋯

 中文：5 分钟过去了……

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

     英文：He published an article entitled "The Future of the Aviation".

 中文：他发表了一篇名为《航空业的未来》的文章。

  5. 第一次出现英文词汇时，在括号中给出中文标注。此后再次出现时，直接使用英文缩写即可。

     IOC（International Olympic Committee，国际奥林匹克委员会）。这样定义后，便可以直接使用“IOC”了。

  6. 专有名词中每个词第一个字母均应大写，非专有名词则不需要大写。

     “American Association of Physicists in Medicine”（美国医学物理学家协会）是专有名词，需要大写。

 “online transaction processing”（在线事务处理）不是专有名词，不应大写。

8 注意事项

  1. 注意文档文本的缩进格式，良好的缩进格式有利于 Markdown 文本的正确渲染。 例如：当在 Markdown 有序列表之间插入图片时，图片代码行须与上一行列表行保持相同的缩进，否则下一行列表行的序号将从头开始计数。

    错误：
1. 内容 1-1

内容1-2

2. 内容 2-1

内容2-2

正确：

1. 内容 1-1

  内容1-2

2. 内容 2-1

  内容2-2

  2. 加粗冒号
    使用加粗冒号 ： 时，其后加一个半角空格才可在网页中正常渲染。

    示例：

**注意：** 请在使用本软件之前阅读硬件相关操作步骤及安全信息。

  3. 尖括号的使用
    在 Markdown 中，尖括号 <> 是用于 HTML 标签的，如果想在 Markdown 中显示 <> 需使用 HTML 实体来表示：

    方法一：使用 &lt; 代替 <，&gt; 代替 >。

    方法二：使用反斜杠 \ 来转义尖括号。（该方式在 gitbook 中不能正常显示）

    注意：<> 之间的内容如果为中文，则不会出现显示不出来的情况；<> 之间的内容如果为英文，gitbook 会直接不显示；如果英文内容与 <> 之间有空格隔开则可以正常显示。

results matching ""

    No results matching ""