# 写作规范<a name="ZH-CN_TOPIC_0000001275063046"></a> ## 文档内容 根据文档分类如用户指南、开发者指南等，选择合适的大纲，要求能简洁清晰的实现文档的目的。 - 开源项目做什么 - 什么语言编写 - 项目维护、CI、依赖更新状态 - 项目可用版本及其他版本 - Demo 或官网地址 - 功能特点 - 获取 - 安装 - 使用（操作步骤、接口文档、开发指南等） - FAQ 拟定文档大纲，编辑文档内容，针对文档内容做如下规范。 - 提交内容必须是与 openEuler 特性相关内容。 - 内容不能包含敏感信息、有强烈的种族歧视或性别歧视的内容。 - 提交的内容必须是原创内容，不得侵犯他人知识产权。 - 提交的内容必须客观、真实，不允许使用夸大宣传等词汇。 ## 文档结构<a name="section1789111817299"></a> 项目手册内容一般包括用户指南、背景介绍、操作类文档（安装与部署、使用指南）、常见问题和附录，写作者可以根据项目实际情况增加或删减。 以[A-Tune 项目为例](https://docs.openeuler.org/zh/docs/22.03_LTS_SP2/docs/A-Tune/A-Tune.html),可以参考如下内容： - **用户指南** 用户指南包含项目介绍和读者对象。 - **背景介绍类** 背景介绍类文档写明项目背景与简介、架构说明等。 - **操作类文档** 操作类文档写明步骤、注意事项、前提条件等，以便能对其他开发者起到帮助。 - 使用说明 说明此操作在什么场景下使用可以解决用户的什么问题。 - 环境要求 执行此操作需要用户准备的软硬件环境、权限以及其它约束条件。 - 操作步骤 具体的操作步骤，需要注意如下事项： - 建议一步一个操作步骤，不建议多个操作步骤合并在一个步骤中描写。 - 如果操作可选，要明确可选条件。 - 开发步骤中，涉及调用接口（例如使用了工具或者 SQL 语句），需要对使用的接口进行说明。 - 结果验证 说明如何验证操作结果正确。如果验证操作与步骤强相关，可以在步骤中描述。例如，执行 SQL 语句的返回信息。 - **常见问题** 此类文档应该包括问题描述、产生原因及解决办法。 - **附录** 附录可包含术语与缩略语介绍。 ## 命名<a name="section196814119284"></a> 对于新增文档，请在对应的文件目录下新增 MarkDown 文档（即以 .md 结尾的文件）。文档命名需要根据文档的内容声明。 - 新增文档名称不能与已有文档重名，如果有请重新命名。 - 新增文档之后，需要在 menu 文件夹下的 index 文件中新增对应的目录，否则新增文件无法显示。目录层级不建议超过三级。 - 文件名中不能包含括号，会导致文件目录无法正常显示。可以将括号修改为可识别的下划线（\_）或者中划线（-）。 ## 标题<a name="section79109619292"></a> - 标题尽量采用简洁的语句概况反映章节的中心内容，注意不要省略必要的信息。例如：xxx概述，如果用概述来代替，就会导致读者无法从标题中获取到有用信息。 - 操作类文档标题尽量用动宾结构（例如：申请权限）。 - 相同级别，相同类型的标题结构保持一致。 - 标题不使用标点符号结尾。 - 标题中尽量采用圆括号来表示补充说明，标题中不能出现特殊字符，如“？”。 - 标题与正文使用 1 整行换行隔开。 - 标题使用 “#” 空格连接标题名，标题级别一次只能增加一个级别且第一个标题应该是顶层标题。 ## 目录<a name="section3226202512810"></a> 文档为以 .md 结尾的文件，存储在<https://gitee.com/openEuler/docs> 路径下。 docs 文件夹中包含以下内容： - zh：全量版中文资料。 - en：全量版英文资料。 根据文档所属的手册，选择对应的文件夹。 - 目录层级不建议过深。 - doc 仓库内新增文档需要同步修改 menu.json 文件，才可以在官网文档页面展示该文档。 - doc 官网会在右侧自动生成文档的章节目录，不建议额外增加 TOC 目录。 ## 正文 - 可使用*斜体* **加粗**样式。 - 该转义的字符必须严格用转义符 \ ，例如 \* \< \> \_等。 - 如果有连续两个转义符，转义符之间要有空格 \{ \}。 - 国际化：需同时提供中英文文档，可联系<zhuyanting@huawei.com>或<hujun33@huawei.com>协助翻译。 ## 空格<a name="section196814119284"></a> - 编辑文档时中文和英文之间建议加空格，页面展示更美观,请保持全文一致。如果是产品名词如 “豆瓣FM”，请按照官方定义格式书写。 例如：openEuler 是一款开源操作系统。当前 openEuler 内核源于 Linux ，支持鲲鹏及其它多种处理器。 - 中文和数字之间加空格。 - 数字和单位之间不加空格。 - 链接与正文之间加空格。 - 全角标点与其他字符之间不加空格。 例如：刚刚成为了 openEuler 的 maintainer，好开心。 ## 图片<a name="section81341219113011"></a> - 图片统一存放到文档同级目录下的 figures 文件夹中。例如，[A-Tune用户指南](https://docs.openeuler.org/zh/docs/22.03_LTS_SP2/docs/A-Tune/A-Tune.html)中的手册中使用的图片，统一存储在 [A-Tune](https://gitee.com/openeuler/docs/tree/stable2-22.03_LTS_SP2/docs/zh/docs/A-Tune/figures) 路径下。该文件夹下的文件引用图片时，使用相对引用。 - 请使用原创图片，避免存在知识产权侵权风险。 - 图形清晰可辨识，图形信息完整，例如流程图有“开始”和“结束”。 - 图形逻辑清晰。 - 图文配合使用，切忌图文分离。 - 图片格式首选 png，此外也接受 jpg。图片的高不超过 640px，宽不超过 393px，图片大小建议不超过 150K。 - 中文用中文插图，英文用英文插图。 - 图片路径不能包含中文。 - 图片后缀也必须是小写，不能出现 .PNG 这种大写后缀 - 图片建议根据内容命名，只用数字序列不利于后续图片的继承。 - 如果是截图，请在允许的范围内只保留有用的信息。图形中需要突出的关键信息，可增加红色框线或者文字备注说明。 图片写作示例： 图片以  格式书写，“./” 不可少，否则图片无法显示到现网。 ## 代码块<a name="section113151222312"></a> 代码示例说明了如何实现特定功能，开发人员使用代码示例来编写和调试代码。代码要求如下： - 代码的逻辑和语法正确。 - 代码的输入和输出尽可能的分开。 - 保证代码中关键步骤要有注释说明。 - 代码源于具体实例。 - 文中行内代码和命令行使用 1 对反引号 如： `代码行`。 - 块级代码使用 3 个顿号或 4 个空格（不能用 TAB 键）缩进，且上下均用整行隔开，如下: ```python #!/usr/bin/env python3 print("Hello, World!"); ``` ```c #include <stdio.h> int main(void) { printf("Hello world\n"); } ``` ## 列表 使用列号 “1.” 或者 “*”，其后内容空格隔开，示例如下： 1. 一层列表 2. 一层列表 3. 一层列表 * 二层列表 * 二层列表 列表内标点符号使用规则： 1. 当项目列表是术语、短语时，统一不加标点符号。 2. 当项目列表是句子时，统一加句号。 3. 特殊情况下如果不能避免出现短语和句子混合的情况，统一加句号。 4. 项目列表前几项以分号结尾，最后一项以句号结尾的形式也可以接受。 ## 注释符号<a name="section1491610719312"></a> 文档中会出现以下注释符号，代表不同的使用场景和提示程度。如果需要提示用户注意的信息，可以根据重要程度选择对应的注释符号。  ## 链接<a name="section4536414123111"></a> 链接需要确保指向的目标文件存在，否则会造成链接跳转不正常，不建议使用 HTML 的链接样式。 链接示例： 这是一个链接 [菜鸟教程](https://www.runoob.com)。 ## 表格 Markdown 文档中请使用以下方式创建表格，不建议使用 HTML 的表格样式。 | 表头 | 表头 | | ---- | ---- | | 单元格 | 单元格 | | 单元格 | 单元格 | 单元格内标点符号使用规则： 1. 当表格内一列全部是术语、短语时，统一不加标点符号。 2. 当表格内一列全部是句子时，统一加句号。 3. 特殊情况下如果不能避免出现短语和句子混合的情况，统一加句号。 ## 常用词汇 | 不建议使用 | 建议使用 | | ---- | ---- | | 阀值 | 阈值 | | 登陆 | 登录 | ## 标点符号 - 单位与数字之间不建议加空格，比如 50m，10kg，64Kbit/s。 - 对于有序/无序列表，如果是长句子，建议统一以句号结尾，如果是短语，结尾可不用标点。**重点是前后一致，要么都加，要么都不加**。 - 中文文档使用全角标点。 - 数字使用半角字符。 - 感叹号使用场景为可能引发严重后果的操作或设备安全、人身安全的警告。其他场景不允许使用感叹号。 - 文内引用其他文档件事添加书名号，同时建议增加引用文档的跳转链接。例如：安装 openEuler 系统，安装方法参考《[openEuler 22.03 LTS SP2 安装指南](https://docs.openeuler.org/zh/docs/22.03_LTS_SP2/docs/Installation/installation.html)》。 ## docs 仓库提交 PR 和 issue 1. PR 规范 - PR 标题清晰易懂，内容描述详细具体，一个 PR 只包含一次提交（git log，git reset commit id , git push -f），一个 PR 只涉及一个主题修改。 - 需要 2 个回复 /lgtm，1 个 /approve，一般需要需求提出或文档相关责任人进行审核。 - CI 格式检查成功，需要满足无 markdownlint 报错。 - PR 需要关联 issue，每个特性需求 /bug 都要转 issue 跟踪，并关联对应版本号。 - 新增文档需要同步修改目录文件 menu.json 文件。 - 对于同步维护的分支，PR 需要分别提交到对应分支上。 2. issue 规范 有文档需要合入需要先新建 issue，内容表述清晰即可，如果是 bug 需要指出具体哪个版本哪本文档需要修改。 3. PR 提交建议 - 修改同一类问题（例如末尾句号）建议全文一致，不仅仅修改一处。 - 建议将同一篇文档的低错问题修改条在一个 PR 里。 - 建议在评论区使用 /sync + 版本号的方式将当前 PR 修改同步到其它分支。 4. 文档贡献中不受欢迎的行为 短时间内通过自动化工具，提交大量的PR，提交大量的处理诸如拼写错误，语法错误，日期错误，语句不通顺等“无害的错误”的修正。 具体内容以及处理措施详见 [openEuler社区开发行为规范 V1.0](https://gitee.com/openeuler/community/blob/master/zh/technical-committee/governance/openEuler%E7%A4%BE%E5%8C%BA%E5%BC%80%E5%8F%91%E8%A1%8C%E4%B8%BA%E8%A7%84%E8%8C%83.md)。 ## 资料PR检视Checklist - **规范和低错类**问题 - 错别字或拼写错误；标点符号使用错误 - 链接错误、空单元格、格式错误 - 英文中包含中文字符 - 界面和描述不一致，但不影响操作 - 表述不通顺，但不影响理解 - 版本号不匹配：如软件包名称、界面版本号 - 相同内容在同一文档中写法不一致 - 软件名称书写不规范 - 描述口语化 - 图形、表格不符合规范 - 专有名词的写作不符合业界规范或拼写错误。 - 成双成对的标点符号使用过程中有缺失另一半，或使用不规范 - 标题和正文中，命令的大小写写法不一致 - 图片不显示、超大，超出正文或页面宽度、变形、缺失或冗余 - 命令解释和命令写在一起 - 相同内容在同一个地方重复描述 - 操作截图与实际环境不一致 - 步骤中命令行和回显中的命令行不一致 - **易用性**问题 - 关键步骤错误或缺失，无法指导用户完成任务 - 缺少必要的前提条件、注意事项等 - 操作场景不明确 - 图形、表格、文字等晦涩难懂 - 逻辑不清晰，该分类、分项、分步骤的没有给出 - 步骤不易理解和学习，如命令缺少描述 - 已明确说明不支持的场景，又给了该场景下的使用方法或约束 - 文档名称不规范，根据文档名称不能快速定位手册描述重点 - 步骤描述和实际的操作不符 - **正确性**问题 - 技术原理、功能、规格、配套版本、OS 等描述和软件不一致，存在错误 - 原理图、架构图等存在错误 - 命令、命令参数、IP等错误 - 命令无法完成对应功能 - 界面错误，无法指导操作 - 链接本来就是错误的，跳转的版本或内容不正确 - 链接未失效，但是所需内容已更新不存在 - 代码格式不规范，如未换行，或缩进不正确，括号没有匹配等 - 命令行中有多余的空格，导致命令报错 - **风险提示**问题 - 对重要数据或系统存在风险的操作，缺少安全提示 - **合规**问题 - 违反法律法规，涉及政治、领土主权等敏感词 - 内容侵权 ## 参考 您如需获取更多写作技巧，请参考 [Markdown常用语法参考](./MarkDown常用语法参考.md)和[markdownlint检查规则](./markdownlint检查规则.md)。