From 973e8bf808010c41805a8544b9534ba611afb36b Mon Sep 17 00:00:00 2001 From: shelly <748706450@qq.com> Date: Mon, 13 Jun 2022 13:35:55 +0000 Subject: [PATCH] =?UTF-8?q?update=203.2=20and=204.2/106-contribute-to-docs?= =?UTF-8?q?.md.=203.2=E5=A2=9E=E5=8A=A0=E5=BD=93=E5=89=8D=E5=8F=AF?= =?UTF-8?q?=E5=8F=82=E4=B8=8E=E7=9A=84=E6=96=87=E6=A1=A3=E8=B4=A1=E7=8C=AE?= =?UTF-8?q?=E6=B4=BB=E5=8A=A8=EF=BC=9B4.2=E5=A2=9E=E5=8A=A0=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E8=A7=84=E8=8C=83=E5=B9=B6=E5=81=9A=E4=BA=86=E5=88=86?= =?UTF-8?q?=E7=B1=BB=E3=80=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- articles/106-contribute-to-docs.md | 61 ++++++++++++++++++++++++------ 1 file changed, 49 insertions(+), 12 deletions(-) diff --git a/articles/106-contribute-to-docs.md b/articles/106-contribute-to-docs.md index 22403af..4baec9f 100644 --- a/articles/106-contribute-to-docs.md +++ b/articles/106-contribute-to-docs.md @@ -57,11 +57,16 @@ ### 3.2 了解有哪些文档任务可以参与 -常见的文档任务有：文档内容修正、文档翻译、主题文档编写等。想要了解详细的正在进行中的文档任务，可以访问[文档 SIG 组](https://openanolis.cn/sig/docs)，并建议参加 SIG 组的会议。 +常见的文档任务有：文档内容修正、文档翻译、主题文档编写等。 -通过 SIG 组会议，或者通过 [Gitee Issues](https://gitee.com/anolis/docs/issues) 页面，你可能会被分到一个具体的文档工作，这个任务将会在 Issues 页面跟踪。 +目前，欢迎开发者来参与以下任务，详情请参见龙蜥社区官网（openanolis.cn）： -领到具体 Issue 后，接下来你就可以基于这个任务进行文档开发了。 +- 文档捉虫活动，找出 SIG 组文档、CentOS 停服专区文档中的 bug，并提交 issue +- 文档翻译活动，将龙蜥社区官网内容翻译为英文 +- 编写用户文档，包括但不限于操作手册、最佳实践、FAQ 等 +- 分享你的开发者故事 + +未来，会在[文档 SIG 组](https://openanolis.cn/sig/docs)中同步正在进行中的文档任务详情。我们正在建设文档 SIG 组，希望感兴趣的开发者一起参与建设，并建议参加 SIG 组的会议。通过 SIG 组会议，或者通过 [Gitee Issues](https://gitee.com/anolis/docs/issues) 页面，你可能会被分到一个具体的文档工作，这个任务将会在 Issues 页面跟踪。领到具体 Issue 后，接下来你就可以基于这个任务进行文档开发了。 ### 3.3 进行文档开发 @@ -126,20 +131,52 @@ OpenAnolis 龙蜥社区相关的术语有如下规范： ### 4.2 文档写作规范 +#### 4.2.1 标题 + 1. 文档的标题应当为一级标题，即使用 Markdown 语法中的 `#` 号。本文档中所有其他标题，都不应再使用一级标题； 2. 文档的各级标题应当用序号标识，请注意序号应当从 1 开始，避免使用标号 0； - 1. 一级标题举例: `## 1. 示例一级标题`; - 2. 二级标题举例: `### 1.1 示例二级标题`; - 3. 三级标题举例: `#### 1.1.1 示例三级标题`(如果还有下一层级)，或者 `#### a. 示例三级标题`(如果没有下一层级)； - 4. 不建议标题使用过多层级，尽量控制在三级及三级以内。 -3. 文档编写过程中，不要求换行（例如100字换行，80字换行），而且我们也不推荐换行操作，对于不同 Markdown 渲染器，换行带来的格式影响是不一致的； -4. 中英文、中文数字混排，**必须**要用空格。即，中文和英文之间，应当使用一个半角空格；中文和数字之间，应当使用一个半角空格。举例如下： + - 一级标题举例: `## 1. 示例一级标题`; + - 二级标题举例: `### 1.1 示例二级标题`; + - 三级标题举例: `#### 1.1.1 示例三级标题`(如果还有下一层级)，或者 `#### a. 示例三级标题`(如果没有下一层级)； + - 不建议标题使用过多层级，尽量控制在三级及三级以内。 +3. 标题格式保持统一： + - 操作类的标题，用动宾结构； + - 描述类的标题，用名词结构； + - FAQ类的标题，用第一人称视角的疑问句。 + +#### 4.2.2 内容 + +1. 文档编写过程中，不要求换行（例如100字换行，80字换行），而且我们也不推荐换行操作，对于不同 Markdown 渲染器，换行带来的格式影响是不一致的； +2. 中英文、中文数字混排，**必须**要用空格。即，中文和英文之间，应当使用一个半角空格；中文和数字之间，应当使用一个半角空格。举例如下： ```md 接受 Reviewer 的检查 # 符合要求 基于PR提交 # 不符合要求 2015 年 10 月 1 日 # 符合要求 2013年3月 # 不符合要求 ``` -5. 嵌入图片的要求，在上一节已经说明； -6. 如果表示突出（但是没有很强烈的强调意味），可以用 `_内容_` 来实现斜体字；如果表示强调，可以用 `**强调**` 来实现粗体字； -7. 文件路径、命令、简短的代码需要使用反引号 '\`' 引用为 inline-quote。例如：`/etc/os-release`, `./execute.sh`；如果是大段代码，需要使用单独的 '\`\`\`' 代码块，并推荐注明对应的代码所属语言。 + +3. 如果表示突出（但是没有很强烈的强调意味），可以用 `_内容_` 来实现斜体字；如果表示强调，可以用 `**强调**` 来实现粗体字； +4. 第一次出现比较新颖的英文或者英文缩写时，要将中英文全称都写出来，例如，龙蜥操作系统（Anolis OS）。 +5. 全文用词保持一致。例如，XXXXX +6. 操作步骤必须完整、正确、可执行，如果步骤较复杂，建议增加截图辅助理解。 +7. 如果是页面上的按钮/标签/窗口等名称，可以用 **加粗** 来体现文案。 +8. 不要有过于口语化的表达，尤其避免出现语气词（呀/吧/呢/啊等等）。 +9. 专用名词，注意使用标准写法，尤其是大小写和空格，例如：Anolis OS。 +10. 避免一些常见的错别字。 +| 正确写法 | 错误写法 | +|------|------| +| 登录 | 登陆 | +| 账号 | 帐号 | + +#### 4.2.3 代码 + +1. 文件路径、命令、简短的代码需要使用反引号 '\`' 引用为 inline-quote。例如：`/etc/os-release`, `./execute.sh`；如果是大段代码，需要使用单独的 '\`\`\`' 代码块，并推荐注明对应的代码所属语言。 +2. 代码中的敏感信息要脱敏，不要出现个人资料、资源ID等信息。 +3. 提供的代码，确保是可正确执行的。 + +#### 4.2.4 图片 +1. 嵌入图片的要求，在上一节已经说明。 +2. 图片只截取必要的部分，不要出现过多无用的干扰信息。 +3. 对于敏感信息（如个人信息、ID信息等），要做好虚化脱敏。 + +规范持续更新中，欢迎一起贡献。 \ No newline at end of file -- Gitee