You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by ju...@apache.org on 2022/05/25 07:20:00 UTC
[apisix-website] branch master updated: docs: update doc style guide (#1105)
This is an automated email from the ASF dual-hosted git repository.
juzhiyuan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix-website.git
The following commit(s) were added to refs/heads/master by this push:
new 797ff67e415 docs: update doc style guide (#1105)
797ff67e415 is described below
commit 797ff67e4153cf6d76e569a67c72c8501e352068
Author: feihan <97...@users.noreply.github.com>
AuthorDate: Wed May 25 15:19:55 2022 +0800
docs: update doc style guide (#1105)
---
website/docs/general/documentation-guide.md | 1 +
.../current/documentation-guide.md | 42 +++++++++++++++-------
.../i18n/zh/docusaurus-theme-classic/footer.json | 2 +-
3 files changed, 32 insertions(+), 13 deletions(-)
diff --git a/website/docs/general/documentation-guide.md b/website/docs/general/documentation-guide.md
index 85c1776bcf5..ef964a988dd 100644
--- a/website/docs/general/documentation-guide.md
+++ b/website/docs/general/documentation-guide.md
@@ -124,3 +124,4 @@ You can learn more about the sidebar from the [Docusaurus docs](https://v2.docus
- The images are currently uploaded to a private CDN to ensure smaller repo size and fast loads. Please reach out to the project team to upload/change an image.
- Use the default APISIX admin account while taking screenshots.
- Provide meaningful file names and alt text for the images.
+- Please do not use a transparent background as the base color of the image. If you use an image with a white background, please make sure that the background color of the image is white, otherwise the text will be blurred when the image is enlarged.
diff --git a/website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md b/website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md
index bbb4d66fdc1..89bf5c5b256 100644
--- a/website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md
+++ b/website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md
@@ -15,26 +15,36 @@ description: Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文
## 语气、内容和受众
-- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”或着直接用“用户需要”等统称。。
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”或着直接用“用户需要”等统称。
- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话或互联网词汇。例如：打满。
- 不使用具有歧义的词汇。例如：“小白”，可更换为“初学者”。
-- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为 数据面（Data Plane，简称 DP）和控制面（Control Plane，简称 CP）。
+- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为数据面（Data Plane，简称 DP）和控制面（Control Plane，简称 CP）。
## 语言
- 写作时请尽量使用第二人称，如果不适用第二人称可统一替换为统称——用户或使用者。
-- 写作时使用主动语态。
+- 写作时使用主动语态，不要使用被动语态。
+- 如果是英译中的文档，需要符合中文阅读习惯，并确保句子通顺，无语病。
+
+:::note
+
+如果部分内容翻译后没有必要或者表达无意义，请根据上下文进行调整或删改。纯机翻没有意义，文档需要给予阅读者清晰明确的指引，而不是毫无意义的文字。
+
+:::
+
+- 涉及到运算符的句子，运算符连接的部分需要使用代码块表示。例如：我们都知道 `2+3=5`。
- 句子要求
- 避免使用长句。不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，任何情况下都不能接受。
- 尽量使用简单句和并列句，避免使用复合句。
- 同样一个意思，尽量使用肯定句表达，不使用否定句表达。
- 避免使用双重否定句。
- - 在标题、正文、导航或目录中，请不要使用 `&` 代替`和`，`/` 代替`或`。请参考[一般注意事项](https://developers.google.com/style/accessibility#general-dos-and-donts) 了解更多信息。
+ - 在标题、正文、导航或目录中，请不要使用`&`代替`和`，`/`代替`或`。请参考[一般注意事项](https://developers.google.com/style/accessibility#general-dos-and-donts)了解更多信息。
+ - 句子中需要正确使用`的`、`地`、`得`。
- 对项目特定词汇使用以下拼写：
- 在介绍中引用项目和引用项目社区时，使用 Apache APISIX 而不是 APISIX。
- 在文档中引用项目时，请使用 APISIX。
- - APISIX 特定的组件名称，如 Plugin、Route、Service 和 Consumer 等组件名称始终保持首字母大写。
+ - APISIX 特定的组件名称，如 Plugin、Route、Service 和 Consumer 等组件名称始终保持首字母大写。如果是表示概念则使用英文书写，如果表示一个实体（例如：创建一个路由），则使用中文名称。
- 必要时使用正确的首字母缩略词，例如：
| ✅ | ❌ |
@@ -54,7 +64,7 @@ description: Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文
- 必要时请使用 Docusaurus 提供的高级功能：
- 当你必须根据用户的配置或环境显示多个路径时，请使用[标签](https://docusaurus.io/docs/next/markdown-features/tabs)和[同步标签选项](https://docusaurus.io/docs/next/markdown-features/tabs#syncing-tab-choices)。
- 使用[代码块](https://docusaurus.io/docs/next/markdown-features/code-blocks)显示代码。
- - 添加正在修改的文件作为代码块的标题（例如：`coonf/config.yaml`）。在解释代码时使用行高亮提高使用者的注意力。
+ - 添加正在修改的文件作为代码块的标题（例如：`./conf/config.yaml`）。在解释代码时使用行高亮提高使用者的注意力。
- 代码是可执行的，不要在代码前加上系统自带符号，例如 `$ cd Desktop` 应修改为 `cd Desktop`。
- 多行多条代码请分别用代码块表示。
- 长代码需要进行格式化处理，让用户直观地看到命令全文。
@@ -68,10 +78,14 @@ description: Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文
- 请使用表格描述恰当的内容。
- 请尽量保证表格内容不包含空置的行和列。
- 表格中的描述需要简洁。
-- 中文与英文、阿拉伯数字之间需要包含一个空格。英文和阿拉伯数字在标点符号前或者标点符号后，不需要加空格。可参考如下示例：
- - APISIX 于 2019 年 10 月加入 Apache 软件基金会。
- - 如果想要使用 `jwt-auth` 插件，你需要创建一个 Route。
-- 在 markdown 文件中请使用相对路径而不是绝对路径。
+- 请正确使用标点符号。在中文文档中，请使用中文标点符号。
+- 空格规范
+ - 中文与英文、阿拉伯数字之间需要包含一个空格。英文和阿拉伯数字在标点符号前或者标点符号后，不需要加空格。可参考如下示例：
+ - APISIX 于 2019 年 10 月加入 Apache 软件基金会。
+ - 如果想要使用 `jwt-auth` 插件，你需要创建一个 Route。
+ - 单位与数字之前需要有空格。
+ - 该连接保持 1 ms。
+- 在 Markdown 文件中请使用相对路径而不是绝对路径。
- 如有多条类似内容进行描述时，请使用列表形式让描述更加清晰。
- 有序列表：通常用来表示列表之间有前后顺序，例如操作步骤。
- 无序列表：无序列表中，各个列表之间属于并列关系，没有先后顺序之分，列表前后需要用空行包围。对于有多项参数或者需要描述的，请使用无序列表。
@@ -79,6 +93,10 @@ description: Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文
- 链接文本需要有意义。例如“请参考 [ApacheAPISIX 官网](https://apisix.apache.org/)”，而不是“请参考[这里](https://apisix.apache.org/)”
- 链接不能裸露。例如：“请参考 https://apisix.apache.org”。
- 内链请使用相对路径。
+ - 如果你需要修改文档内的目录，请确保没有其他文档引用它。如果其他文档引用了你需要修改的内容，请一并修改其他文档。
+ - 如果你引用的内容有中文版本，请使用中文链接。
+- 对于需要在代码或者文本中表示一个变量的，请使用`${变量名称}`。
+- 如果一个值表示的是字符串，请使用`"1"`。如果表示的是一个数值，请使用`1`。
### 目录结构
@@ -101,7 +119,6 @@ description: Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文
│ └── folder2
│ └── doc3.md
│
-
```
### 配置文件
@@ -151,7 +168,8 @@ description: Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文
- 请使用高分辨率的图片，使所呈现的信息对用户清晰可见。
- 目前 APISIX 官网文档中所需图片需要上传到私有 CDN，以确保更小的存储库大小和快速加载。如需在文档中添加图片，请联系项目团队以上传/更改图片。
- 在截屏时请使用默认的 APISIX 管理员帐户。
-- 在添加图片时，切勿只放图片链接而不添加概述，否则 Lint 出现报错情况。正常图片链接应为： ![图片是干什么的](图片链接）。
+- 在添加图片时，切勿只放图片链接而不添加描述，否则会 Lint 出现报错情况。正常图片链接应为：![图片描述](图片链接）。
+- 请不要使用透明背景作为图片的底色。如果使用的图片为白色背景，请确保图片底色为白色，否则图片放大后会导致文字模糊。
## 文档架构
diff --git a/website/i18n/zh/docusaurus-theme-classic/footer.json b/website/i18n/zh/docusaurus-theme-classic/footer.json
index 1d75195460f..9d5c4f20ac2 100644
--- a/website/i18n/zh/docusaurus-theme-classic/footer.json
+++ b/website/i18n/zh/docusaurus-theme-classic/footer.json
@@ -52,7 +52,7 @@
"description": "The label of footer link with label=Blog linking to https://apisix.apache.org/blog/"
},
"copyright": {
- "message": "Copyright © 2019-2021 The Apache Software Foundation. Apache APISIX, APISIX®, Apache, the Apache feather logo, and the Apache APISIX project logo are either registered trademarks or trademarks of the Apache Software Foundation.",
+ "message": "Copyright © 2019-2022 The Apache Software Foundation. Apache APISIX, APISIX®, Apache, the Apache feather logo, and the Apache APISIX project logo are either registered trademarks or trademarks of the Apache Software Foundation.",
"description": "The footer copyright"
}
}