写作规范 ​

本写作规范针对openEuler docs 仓的文档结构、内容元素和语言风格提出规范要求，确保openEuler文档具备一致风格。

开发者开始openEuler文档写作前，建议先了解本规范内容，欢迎提出改进意见。

文档结构规范 ​

特性手册内容一般包括概述、背景介绍、操作类文档（安装与部署、使用指南）、常见问题和附录，开发者可以根据项目实际情况增加或删减。 以A-Tune 项目为例，可以参考如下内容：

概述 ​

一句话介绍特性定义与功能，一句话说明读者对象。

【举例】

本文档介绍openEuler系统性能自优化软件A-Tune的安装部署和使用方法，以指导开发者快速了解并使用A-Tune。
本文档适用于使用openEuler系统并希望了解和使用A-Tune的社区开发者、开源爱好者以及相关合作伙伴，使用人员需要具备基本的Linux操作系统知识。

背景介绍 ​

背景介绍类文档写明特性背景与简介、架构说明等。常见文档标题：认识xxx。

操作类文档 ​

• 环境要求

执行此操作需要准备的软硬件环境、权限以及其它约束条件。

【举例】

硬件要求：xxx处理器。
软件要求：openEuler xx版本、root权限。

• 操作步骤

操作步骤文档包含安装与部署、使用方法等说明内容。

具体的操作步骤，需要注意如下事项:

- 建议一步一个操作步骤，不建议多个操作步骤合并在一个步骤中描写。
- 如果操作可选，要明确可选条件。
- 开发步骤中，涉及调用接口（例如使用了工具或者 SQL 语句），需要对使用的接口进行说明。

• 结果验证

说明如何验证操作结果正确。如果验证操作与步骤强相关，可以在步骤中描述。例如，执行 SQL 语句的返回信息。

附录 ​

附录可包含术语与缩略语介绍。

内容元素规范 ​

命名 ​

对于新增文档，请在对应的文件目录下新增 MarkDown 文档（即以 .md 结尾的文件）。

【规则】新增文档名称不能与已有文档重名，如果有请重新命名。

【规则】文档需要以英文命名。

【规则】文件名中不能包含括号，会导致文件目录无法正常显示。可以将括号修改为可识别的下划线（_）或者中划线（-）。

【举例】

installation_and_deployment.md  #新增‘安装与部署’文档

标题 ​

【规则】标题尽量采用简洁的语句概况反映章节的中心内容，注意不要省略必要的信息。

【规则】操作类文档标题尽量用动宾结构（例如：申请权限）；相同级别，相同类型的标题结构保持一致。

【规则】标题不使用标点符号结尾，标题中尽量采用圆括号来表示补充说明，标题中不能出现特殊字符，如“？”。

【规则】标题与正文使用 1 整行换行隔开。

【规则】标题使用 “#” 空格连接标题名，标题级别一次只能增加一个级别且第一个标题应该是顶层标题。

【举例】

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

正文 ​

【使用方法】

• 斜体：使用一个星号（*）表示斜体。

  txt

  *斜体文本*

• 粗体：使用两个星号（**）表示粗体。

  txt

  **粗体文本**

• 粗斜体：使用3个星号（***）表示粗斜体。

  txt

  ***粗斜体文本***

• 转义：对特定内容使用转义符 \。

  txt

  \<转义的标记符号>

【规则】该转义的字符必须严格用转义符 \ 。

【规则】如果有连续两个转义符，转义符之间要有空格 { }。

【规则】国际化：需同时提供中英文文档，可联系liujingrong3@huawei.com或wudonger@huawei.com协助翻译；如需参与英文文档贡献，可参考指南。

空格 ​

【规则】编辑文档时中文和英文之间建议加空格，页面展示更美观，请保持全文一致。如果是产品名词如 “豆瓣FM”，请按照官方定义格式书写。

例如：openEuler 是一款开源操作系统。当前 openEuler 内核源于 Linux ，支持鲲鹏及其它多种处理器。

【规则】中文和数字之间加空格。

【规则】数字和单位之间不加空格。

【规则】全角标点与其他字符之间不加空格。

例如：刚刚成为了 openEuler 的 maintainer，好开心。

图片 ​

【使用方法】

![alt 属性文本](图片地址)
 
![alt 属性文本](图片地址 "可选标题")

【规则】图片统一存放到文档同级目录下的 figures 文件夹中。例如，A-Tune用户指南中的手册中使用的图片，统一存储在 A-Tune 路径下。该文件夹下的文件引用图片时，使用相对引用。

【规则】请使用原创图片，避免存在知识产权侵权风险。

【规则】图文配合使用，切忌图文分离。

【规则】图片格式首选 png，此外也接受 jpg。图片的高不超过 640px，宽不超过 393px，图片大小建议不超过 150K。

【规则】中文用中文插图，英文用英文插图。

【规则】图片路径不能包含中文。

【规则】如果是截图，请在允许的范围内只保留有用的信息。图形中需要突出的关键信息，可增加红色框线或者文字备注说明。

【举例】 ​图片以 ![](./figures/ci检查结果.jpg) 格式书写，“./” 不可少，否则图片无法显示到现网。

代码块 ​

代码示例说明了如何实现特定功能，开发人员使用代码示例来编写和调试代码。

【规则】代码的逻辑和语法正确。

【规则】代码的输入和输出尽可能的分开。

【规则】保证代码中关键步骤要有注释说明。

【规则】文中行内代码和命令行使用 1 对反引号，如： 代码块。

【规则】块级代码使用 3 个顿号或 4 个空格（不能用 TAB 键）缩进，且上下均用整行隔开。

【举例】

• 行内代码

  txt

  `printf()` 函数

• 块级代码

  python

  #!/usr/bin/env python3
  print("Hello, World!");

  c

  #include  <stdio.h>
  int main(void)
  {
      printf("Hello world\n");
  }

列表 ​

• 无序列表：无序列表使用星号（*）、加号（+）或是减号（-）作为列表标记，这些标记后面要添加一个空格，然后再填写内容。同一个无序列表，建议使用同一个符号。

  txt

  * 第一项
  * 第二项
  * 第三项
   
  + 第一项
  + 第二项
  + 第三项
   
   
  - 第一项
  - 第二项
  - 第三项

• 有序列表：有序列表使用数字并加上 . 号来表示。

  txt

  1. 第一项
  2. 第二项
  3. 第三项

• 嵌套列表：列表嵌套只需在子列表中的选项前面添加四个空格（注意不是Tab键）即可。

  txt

  1. 第一项：
      - 第一项嵌套的第一个元素
      - 第一项嵌套的第二个元素
  2. 第二项：
      - 第二项嵌套的第一个元素
      - 第二项嵌套的第二个元素

【规则】有明显先后逻辑顺序情况请使用有序列表，并列关系、多选一情况请使用无序列表。

【规则】当项目列表是术语、短语时，统一不加标点符号。

【规则】当项目列表是句子时，统一加句号。

【规则】特殊情况下如果不能避免出现短语和句子混合的情况，统一加句号。

【规则】项目列表前几项以分号结尾，最后一项以句号结尾的形式也可以接受。

注释符号 ​

文档中会出现以下注释符号，代表不同的使用场景和提示程度。如果需要提示用户注意的信息，可以根据重要程度选择对应的注释符号。

链接 ​

【规则】链接需要确保指向的目标文件存在，否则会造成链接跳转不正常，不建议使用 HTML 的链接样式。

【举例】

- 网站链接
这是一个链接 [菜鸟教程](https://www.runoob.com)。

- 相对路径
 [文档开发流水线门禁](./ci_rules.md)

表格 ​

【规则】markdown 文档中请使用以下方式创建表格，不建议使用 HTML 的表格样式。

【举例】

【使用方法】 设置表格的对齐方式：

• -: 设置内容和标题栏居右对齐。
• :- 设置内容和标题栏居左对齐。
• :-: 设置内容和标题栏居中对齐。

【规则】当表格内一列全部是术语、短语时，统一不加标点符号。

【规则】当表格内一列全部是句子时，统一加句号。

【规则】特殊情况下如果不能避免出现短语和句子混合的情况，统一加句号。

标点符号 ​

【规则】单位与数字之间不建议加空格，比如 50m，10kg，64Kbit/s。

【规则】对于有序/无序列表，如果是长句子，建议统一以句号结尾，如果是短语，结尾可不用标点。重点是前后一致，要么都加，要么都不加。

【规则】中文文档使用全角标点。

【规则】数字使用半角字符。

【规则】感叹号使用场景为可能引发严重后果的操作或设备安全、人身安全的警告。其他场景不允许使用感叹号。

【规则】文内引用其他文档时添加书名号，同时建议增加引用文档的跳转链接。例如：安装 openEuler 系统，安装方法参考《openEuler 22.03 LTS SP2 安装指南》。

语言风格规范 ​

【规则】提交内容必须是与 openEuler 特性相关内容。

【规则】内容不能包含敏感信息、有强烈的种族歧视或性别歧视的内容。

【规则】提交的内容必须是原创内容，不得侵犯他人知识产权。

【规则】提交的内容必须客观、真实，不允许使用夸大宣传等词汇。

文档贡献中不受欢迎的行为

短时间内通过自动化工具，提交大量的PR，提交大量的处理诸如拼写错误，语法错误，日期错误，语句不通顺等“无害的错误”的修正。 具体内容以及处理措施详见 openEuler社区开发行为规范 V1.0。