You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by GitBox <gi...@apache.org> on 2022/04/25 15:36:49 UTC

[GitHub] [apisix-website] hf400159 opened a new pull request, #1056: docs: update the Chinese Documentation style guide

hf400159 opened a new pull request, #1056:
URL: https://github.com/apache/apisix-website/pull/1056

   update the Chinese Documentation style guide.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-website] yzeng25 commented on pull request #1056: docs: update the Chinese Documentation style guide

Posted by GitBox <gi...@apache.org>.
yzeng25 commented on PR #1056:
URL: https://github.com/apache/apisix-website/pull/1056#issuecomment-1109702524

   > > Another thought: Is it a really urgent thing to do? I see discussions of changing the website from Docusaurus to Hexo or Hugo in June. How much of this article is applicable after framework is changed? How much extra work is needed after the change?
   > 
   > Much of the documentation style is platform-independent and may require changes to advanced features of Docusaurus. Anyway, make sure there is content first, if it is changed to Hexo or Hugo I can modify it.
   
   Agree.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-website] SylviaBABY commented on a diff in pull request #1056: docs: update the Chinese Documentation style guide

Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #1056:
URL: https://github.com/apache/apisix-website/pull/1056#discussion_r858166279


##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者，贡献者应遵循此文档以确保文档一致性。
+
+要了解关于贡献的更多信息，请参考 [Contributor Guide](../docs/general/contributor-guide.md)。
+
+## 语气、内容和受众
+
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”。
+- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
+- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话。例如：打满。
+- 不使用侮辱性词汇。例如：“小白”，可更换为“初学者”。
+- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为 Data Plane（数据面）和 Control Plane（控制面）。
+
+## 语言
+
+- 写作时请尽量使用第二人称，如果不适用第二人称可换成其他人称。
+- 写作时使用主动语态。
+- 句子要求
+  - 避免使用长句。不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，任何情况下都不能接受。
+  - 尽量使用简单句和并列句，避免使用复合句。
+  - 同样一个意思，尽量使用肯定句表达，不使用否定句表达。
+  - 避免使用双重否定句。
+- 请不要在标题、文本、导航或目录中使用`&`代替`和`，`/` 代替 `或`。请参考[一般注意事项](https://developers.google.com/style/accessibility#general-dos-and-donts) 了解更多信息。
+- 对项目特定词汇使用以下拼写：
+  - 在介绍中引用项目和引用项目社区时，使用 Apache APISIX 而不是 APISIX。
+  - 在文档中引用项目时，请使用 APISIX。
+  - APISIX 特定的组件名称，如 Plugin、Route、Service 和 Consumer 等组件名称始终保持首字母大写。
+  - 必要时使用正确的首字母缩略词，例如：
+
+    | ✅              | ❌               |
+    | ---------------- | ---------------- |
+    | URL              | url              |
+    | API              | api              |
+    | APISIX Dashboard | Apisix dashboard |
+    | gRPC             | GRPC/grpc        |
+    | NGINX            | Nginx            |
+
+## 格式、标点和目录
+
+- 标题和副标题应当是有意义的，可以概括文档内容。
+- 必要时请使用 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`）。在解释代码时使用行高亮提高使用者的注意力。
+    - 代码需要是可执行，建议不要在代码前加上系统自带符号。
+    - 多行多条代码请分别用代码块表示。
+    - 长代码需要进行格式化处理，让用户直观的看到命令全文。
+  - 使用[admonitions](https://docusaurus.io/docs/next/markdown-features/admonitions) 突出显示重要信息。按照以下建议使用它们：
+    - Tip：为用户提供基于其他内容的额外提示。一般可以忽略。
+    - Note：想要突出的一般信息，该信息需要用户关注的。
+    - Important：用户需要关注的一般信息，该信息可能需要用户特别注意。
+    - Warning：用户需要特别关注的信息，该操作可能会导致配置或者数据丢失。
+    - Danger：用户应该非常小心该提示中提到的内容，仅在最严重的情况下使用，该操作会导致配置或者数据丢失。
+- 请使用表格描述恰当的内容。请参考[常见问题](/docs/apisix/FAQ#what-is-the-difference-between-plugin-metadata-and-plugin-configs-in-apache-apisix)。
+  - 表格中如果尽量不包含空列和空行。
+  - 表格中的描述需要简洁。
+- 中文与英文、阿拉伯数字之间需要包含一个空格。英文和阿拉伯数字在标点符号前或者标点符号后，不需要加空格。
+- 在 markdown 文件中请使用相对路径而不是绝对路径。
+- 请使用列表使描述更加清晰。
+  - 有序列表：通常用来表示列表之间有前后顺序，例如操作步骤。
+  - 无序列表：无序列表中，各个列表之间属于并列关系，没有先后顺序之分，列表前后需要用空行包围。对于有多项参数或者需要描述的，请使用无序列表。
+- 链接
+  - 链接文本需要有意义。例如“请参考[ApacheAPISIX 官网](https://apisix.apache.org/)”，而不是 “请参考[这里](https://apisix.apache.org/)”
+  - 链接不能裸露。例如：“请参考https://apisix.apache.org”。
+  - 内链请使用相对路径。
+
+### 目录结构
+
+文档的目录如下所示。如果要创建新文档，请选择文档写作时所用语言的 `latest` 文件夹中创建一个新文件。
+
+```text
+/docs
+├── assets
+│   ├── images
+│   │   ├── xxxxx.png
+│   └── other
+│       └── xxxxx.xxx
+├── en
+│   └── latest
+│       ├── doc1.md
+│       └── folder
+│           └── doc2.md
+│               └── folder2
+│                   └── doc3.md
+│
+└── zh
+    └── latest
+        └── ...
+```
+
+### 配置文件
+
+配置文件位于 `/docs/<locale>/latest/config.json` 中，其中 locale 表示区域设置代码（语言）。有关详细信息，请参考[本地语言](https://www.science.co.il/language/Locale-codes.php)。请注意，语言环境全部都是小写。
+
+您可以从 [Docusaurus 文档](https://v2.docusaurus.io/docs/next/sidebar)中了解有关侧边栏的更多信息。
+
+```json
+{
+  "version": 2.3,
+  "sidebar": [
+    // The left sidebar of the APISIX website
+    {
+      "type": "doc",
+      "id": "doc2" // id is the filename of the md file
+    },
+    {
+      "type": "category", // category is a collapsed column, nestable
+      "label": "folder",
+      "items": [
+        {
+          "type": "doc",
+          "id": "folder/doc2"
+        },
+        {
+          "type": "category",
+          "label": "folder2",
+          "items": [
+            "folder2/doc3"
+          ]
+        }
+      ]
+    },
+    {
+      "type": "link",
+      "label": "CHANGELOG",
+      "href": "https://github.com/apache/apisix/blob/master/CHANGELOG"
+    }
+  ]
+}
+```
+
+## 图片和嵌入内容
+
+- 请使用高质量的图片，使所呈现的信息对用户清晰可见。
+- 图片需要当前上传到私有 CDN，以确保更小的存储库大小和快速加载。请联系项目团队以上传/更改图片。
+- 在截屏时请使用默认的 APISIX 管理员帐户。
+- 为图片提供有意义的文件名和替代文本。

Review Comment:
   ```suggestion
   - 为图片提供有意义的文件名和替代文本。在添加图片时，切勿只放图片链接而不添加概述，否则 Lint 出现报错情况。正常图片链接应为： ![图片是干什么的](图片链接）
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-website] SylviaBABY commented on a diff in pull request #1056: docs: update the Chinese Documentation style guide

Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #1056:
URL: https://github.com/apache/apisix-website/pull/1056#discussion_r858310963


##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,169 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API 网关
+  - APISIX
+  - Apache APISIX
+  - 中文文档写作指南
+description: Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者。
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于为 APISIX 贡献中文文档的开发者，贡献者应遵循此文档以确保文档一致性。
+
+要了解关于贡献的更多信息，请参考[代码贡献流程](../docs/general/contributor-guide.md)。
+
+## 语气、内容和受众
+
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”或着直接用“用户需要”等统称。。
+- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
+- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话或互联网词汇。例如：打满。
+- 不使用具有歧义的词汇。例如：“小白”，可更换为“初学者”。
+- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为 数据面（Data Plane，简称 DP）和控制面（Control Plane，简称 CP）。
+
+## 语言
+
+- 写作时请尽量使用第二人称，如果不适用第二人称可统一替换为统称——用户或使用者。
+- 写作时使用主动语态。
+- 句子要求
+  - 避免使用长句。不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，任何情况下都不能接受。
+  - 尽量使用简单句和并列句，避免使用复合句。
+  - 同样一个意思，尽量使用肯定句表达，不使用否定句表达。
+  - 避免使用双重否定句。
+  - 在标题、正文、导航或目录中，请不要使用 `&` 代替`和`，`/` 代替`或`。请参考[一般注意事项](https://developers.google.com/style/accessibility#general-dos-and-donts) 了解更多信息。
+- 对项目特定词汇使用以下拼写：
+  - 在介绍中引用项目和引用项目社区时，使用 Apache APISIX 而不是 APISIX。
+  - 在文档中引用项目时，请使用 APISIX。
+  - APISIX 特定的组件名称，如 Plugin、Route、Service 和 Consumer 等组件名称始终保持首字母大写。
+  - 必要时使用正确的首字母缩略词，例如：
+
+    | ✅              | ❌               |
+    | ---------------- | ---------------- |
+    | URL              | url              |
+    | API              | api              |
+    | APISIX Dashboard | Apisix dashboard |
+    | gRPC             | GRPC/grpc        |
+    | NGINX            | Nginx            |
+
+    如不清楚某些词汇到底应该以哪种形态出现，请及时使用搜索引擎进行查询。
+
+## 格式、标点和目录
+
+- 关于 Markdown 使用指南，请参考 [Markdown 基本要素](https://shd101wyy.github.io/markdown-preview-enhanced/#/zh-cn/markdown-basics)
+- 标题和副标题应当是有意义且简短概括的，不要出现「短句」来充当标题的现象。
+- 必要时请使用 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`）。在解释代码时使用行高亮提高使用者的注意力。
+    - 代码是可执行的，不要在代码前加上系统自带符号，例如 `$ cd Desktop` 应修改为 `cd Desktop`。
+    - 多行多条代码请分别用代码块表示。
+    - 长代码需要进行格式化处理，让用户直观地看到命令全文。
+    - 命令与返回结果需要使用不同的代码块进行展示。
+  - 使用 [admonitions](https://docusaurus.io/docs/next/markdown-features/admonitions) 突出显示重要信息。以下是每个 admonitions 的使用场景：
+    - Tip：为用户提供基于其他内容的额外提示。一般可以忽略。
+    - Note：想要突出的一般信息，该信息需要用户关注的。
+    - Important：用户需要关注的一般信息，该信息可能需要用户特别注意。
+    - Warning：用户需要特别关注的信息，该操作可能会导致配置或者数据丢失。
+    - Danger：用户应该非常小心该提示中提到的内容，仅在最严重的情况下使用，该操作会导致配置或者数据丢失。
+- 请使用表格描述恰当的内容。
+  - 请尽量保证表格内容不包含空置的行和列。
+  - 表格中的描述需要简洁。
+- 中文与英文、阿拉伯数字之间需要包含一个空格。英文和阿拉伯数字在标点符号前或者标点符号后，不需要加空格。可参考如下示例：
+  - APISIX 于 2019 年 10 月加入 Apache 软件基金会。
+  - 如果想要使用 `jwt-auth` 插件，你需要创建一个 Route。
+- 在 markdown 文件中请使用相对路径而不是绝对路径。
+- 如有多条类似内容进行描述时，请使用列表形式让描述更加清晰。
+  - 有序列表：通常用来表示列表之间有前后顺序，例如操作步骤。
+  - 无序列表：无序列表中，各个列表之间属于并列关系，没有先后顺序之分，列表前后需要用空行包围。对于有多项参数或者需要描述的，请使用无序列表。
+- 链接
+  - 链接文本需要有意义。例如“请参考 [ApacheAPISIX 官网](https://apisix.apache.org/)”，而不是“请参考[这里](https://apisix.apache.org/)”
+  - 链接不能裸露。例如：“请参考 https://apisix.apache.org”。
+  - 内链请使用相对路径。
+
+### 目录结构
+
+目前，Apache APISIX 官网的文档目录如下所示。如果要创建新文档，请选择文档写作时所用语言的 `latest` 文件夹中创建一个新文件。
+
+```text
+/docs
+├── assets
+│   ├── images
+│   │   ├── xxxxx.png
+│   └── other
+│       └── xxxxx.xxx
+├── en
+│
+└── zh
+|    └── latest
+|        ├── doc1.md
+│       └── folder
+│           └── doc2.md
+│               └── folder2
+│                   └── doc3.md
+│
+
+```
+
+### 配置文件
+
+配置文件位于 `/docs/<locale>/latest/config.json` 中，其中 locale 表示区域设置代码（语言）。有关详细信息，请参考[本地语言](https://www.science.co.il/language/Locale-codes.php)。请注意，语言环境全部都是小写。
+
+您可以从 [Docusaurus 文档](https://v2.docusaurus.io/docs/next/sidebar)中了解有关侧边栏的更多信息。
+
+```json
+{
+  "version": 2.3,
+  "sidebar": [
+    // The left sidebar of the APISIX website
+    {
+      "type": "doc",
+      "id": "doc2" // id is the filename of the md file
+    },
+    {
+      "type": "category", // category is a collapsed column, nestable
+      "label": "folder",
+      "items": [
+        {
+          "type": "doc",
+          "id": "folder/doc2"
+        },
+        {
+          "type": "category",
+          "label": "folder2",
+          "items": [
+            "folder2/doc3"
+          ]
+        }
+      ]
+    },
+    {
+      "type": "link",
+      "label": "CHANGELOG",
+      "href": "https://github.com/apache/apisix/blob/master/CHANGELOG"
+    }
+  ]
+}
+```
+
+## 为你的文章添加图片
+
+- 支持的图片格式包括：PNG，JPG 等。
+- 请使用高分辨率的图片，使所呈现的信息对用户清晰可见。
+- 目前 APISIX 官网文档中所需图片需要上传到私有 CDN，以确保更小的存储库大小和快速加载。如需在文档中添加图片，请联系项目团队以上传/更改图片。
+- 在截屏时请使用默认的 APISIX 管理员帐户。
+- 在添加图片时，切勿只放图片链接而不添加概述，否则 Lint 出现报错情况。正常图片链接应为： ![图片是干什么的](图片链接）。
+
+## 文档架构
+
+如需在本网站【文档-Apache APISIX】下添加技术文档（插件类文档），可参考以下内容架构：
+
+- 插件描述（使用该插件可以做什么，为什么开发了此插件等背景信息）；
+- 属性（使用该插件时可以配置哪些属性。）；

Review Comment:
   ```suggestion
   - 属性（使用该插件时可以配置哪些属性）；
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-website] SylviaBABY commented on a diff in pull request #1056: docs: update the Chinese Documentation style guide

Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #1056:
URL: https://github.com/apache/apisix-website/pull/1056#discussion_r858163956


##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者，贡献者应遵循此文档以确保文档一致性。
+
+要了解关于贡献的更多信息，请参考 [Contributor Guide](../docs/general/contributor-guide.md)。
+
+## 语气、内容和受众
+
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”。
+- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
+- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话。例如：打满。
+- 不使用侮辱性词汇。例如：“小白”，可更换为“初学者”。
+- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为 Data Plane（数据面）和 Control Plane（控制面）。
+
+## 语言
+
+- 写作时请尽量使用第二人称，如果不适用第二人称可换成其他人称。
+- 写作时使用主动语态。
+- 句子要求
+  - 避免使用长句。不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，任何情况下都不能接受。
+  - 尽量使用简单句和并列句，避免使用复合句。
+  - 同样一个意思，尽量使用肯定句表达，不使用否定句表达。
+  - 避免使用双重否定句。
+- 请不要在标题、文本、导航或目录中使用`&`代替`和`，`/` 代替 `或`。请参考[一般注意事项](https://developers.google.com/style/accessibility#general-dos-and-donts) 了解更多信息。
+- 对项目特定词汇使用以下拼写：
+  - 在介绍中引用项目和引用项目社区时，使用 Apache APISIX 而不是 APISIX。
+  - 在文档中引用项目时，请使用 APISIX。
+  - APISIX 特定的组件名称，如 Plugin、Route、Service 和 Consumer 等组件名称始终保持首字母大写。
+  - 必要时使用正确的首字母缩略词，例如：
+
+    | ✅              | ❌               |
+    | ---------------- | ---------------- |
+    | URL              | url              |
+    | API              | api              |
+    | APISIX Dashboard | Apisix dashboard |
+    | gRPC             | GRPC/grpc        |
+    | NGINX            | Nginx            |
+
+## 格式、标点和目录
+
+- 标题和副标题应当是有意义的，可以概括文档内容。

Review Comment:
   ```suggestion
   - 标题和副标题应当是有意义且简短概括的，不要出现「短句」来充当标题的现象。
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-website] SylviaBABY commented on a diff in pull request #1056: docs: update the Chinese Documentation style guide

Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #1056:
URL: https://github.com/apache/apisix-website/pull/1056#discussion_r858164416


##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者，贡献者应遵循此文档以确保文档一致性。
+
+要了解关于贡献的更多信息，请参考 [Contributor Guide](../docs/general/contributor-guide.md)。
+
+## 语气、内容和受众
+
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”。
+- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
+- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话。例如：打满。
+- 不使用侮辱性词汇。例如：“小白”，可更换为“初学者”。
+- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为 Data Plane（数据面）和 Control Plane（控制面）。
+
+## 语言
+
+- 写作时请尽量使用第二人称，如果不适用第二人称可换成其他人称。
+- 写作时使用主动语态。
+- 句子要求
+  - 避免使用长句。不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，任何情况下都不能接受。
+  - 尽量使用简单句和并列句，避免使用复合句。
+  - 同样一个意思，尽量使用肯定句表达，不使用否定句表达。
+  - 避免使用双重否定句。
+- 请不要在标题、文本、导航或目录中使用`&`代替`和`，`/` 代替 `或`。请参考[一般注意事项](https://developers.google.com/style/accessibility#general-dos-and-donts) 了解更多信息。
+- 对项目特定词汇使用以下拼写：
+  - 在介绍中引用项目和引用项目社区时，使用 Apache APISIX 而不是 APISIX。
+  - 在文档中引用项目时，请使用 APISIX。
+  - APISIX 特定的组件名称，如 Plugin、Route、Service 和 Consumer 等组件名称始终保持首字母大写。
+  - 必要时使用正确的首字母缩略词，例如：
+
+    | ✅              | ❌               |
+    | ---------------- | ---------------- |
+    | URL              | url              |
+    | API              | api              |
+    | APISIX Dashboard | Apisix dashboard |
+    | gRPC             | GRPC/grpc        |
+    | NGINX            | Nginx            |
+
+## 格式、标点和目录
+
+- 标题和副标题应当是有意义的，可以概括文档内容。
+- 必要时请使用 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`）。在解释代码时使用行高亮提高使用者的注意力。
+    - 代码需要是可执行，建议不要在代码前加上系统自带符号。
+    - 多行多条代码请分别用代码块表示。
+    - 长代码需要进行格式化处理，让用户直观的看到命令全文。
+  - 使用[admonitions](https://docusaurus.io/docs/next/markdown-features/admonitions) 突出显示重要信息。按照以下建议使用它们：
+    - Tip：为用户提供基于其他内容的额外提示。一般可以忽略。
+    - Note：想要突出的一般信息，该信息需要用户关注的。
+    - Important：用户需要关注的一般信息，该信息可能需要用户特别注意。
+    - Warning：用户需要特别关注的信息，该操作可能会导致配置或者数据丢失。
+    - Danger：用户应该非常小心该提示中提到的内容，仅在最严重的情况下使用，该操作会导致配置或者数据丢失。
+- 请使用表格描述恰当的内容。请参考[常见问题](/docs/apisix/FAQ#what-is-the-difference-between-plugin-metadata-and-plugin-configs-in-apache-apisix)。
+  - 表格中如果尽量不包含空列和空行。
+  - 表格中的描述需要简洁。
+- 中文与英文、阿拉伯数字之间需要包含一个空格。英文和阿拉伯数字在标点符号前或者标点符号后，不需要加空格。
+- 在 markdown 文件中请使用相对路径而不是绝对路径。
+- 请使用列表使描述更加清晰。

Review Comment:
   ```suggestion
   - 如有多条类似内容进行描述时，请使用列表形式让描述更加清晰。
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-website] SylviaBABY commented on a diff in pull request #1056: docs: update the Chinese Documentation style guide

Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #1056:
URL: https://github.com/apache/apisix-website/pull/1056#discussion_r858164821


##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者，贡献者应遵循此文档以确保文档一致性。
+
+要了解关于贡献的更多信息，请参考 [Contributor Guide](../docs/general/contributor-guide.md)。
+
+## 语气、内容和受众
+
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”。
+- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
+- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话。例如：打满。
+- 不使用侮辱性词汇。例如：“小白”，可更换为“初学者”。
+- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为 Data Plane（数据面）和 Control Plane（控制面）。
+
+## 语言
+
+- 写作时请尽量使用第二人称，如果不适用第二人称可换成其他人称。
+- 写作时使用主动语态。
+- 句子要求
+  - 避免使用长句。不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，任何情况下都不能接受。
+  - 尽量使用简单句和并列句，避免使用复合句。
+  - 同样一个意思，尽量使用肯定句表达，不使用否定句表达。
+  - 避免使用双重否定句。
+- 请不要在标题、文本、导航或目录中使用`&`代替`和`，`/` 代替 `或`。请参考[一般注意事项](https://developers.google.com/style/accessibility#general-dos-and-donts) 了解更多信息。
+- 对项目特定词汇使用以下拼写：
+  - 在介绍中引用项目和引用项目社区时，使用 Apache APISIX 而不是 APISIX。
+  - 在文档中引用项目时，请使用 APISIX。
+  - APISIX 特定的组件名称，如 Plugin、Route、Service 和 Consumer 等组件名称始终保持首字母大写。
+  - 必要时使用正确的首字母缩略词，例如：
+
+    | ✅              | ❌               |
+    | ---------------- | ---------------- |
+    | URL              | url              |
+    | API              | api              |
+    | APISIX Dashboard | Apisix dashboard |
+    | gRPC             | GRPC/grpc        |
+    | NGINX            | Nginx            |
+
+## 格式、标点和目录
+
+- 标题和副标题应当是有意义的，可以概括文档内容。
+- 必要时请使用 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`）。在解释代码时使用行高亮提高使用者的注意力。
+    - 代码需要是可执行，建议不要在代码前加上系统自带符号。
+    - 多行多条代码请分别用代码块表示。
+    - 长代码需要进行格式化处理，让用户直观的看到命令全文。
+  - 使用[admonitions](https://docusaurus.io/docs/next/markdown-features/admonitions) 突出显示重要信息。按照以下建议使用它们：
+    - Tip：为用户提供基于其他内容的额外提示。一般可以忽略。
+    - Note：想要突出的一般信息，该信息需要用户关注的。
+    - Important：用户需要关注的一般信息，该信息可能需要用户特别注意。
+    - Warning：用户需要特别关注的信息，该操作可能会导致配置或者数据丢失。
+    - Danger：用户应该非常小心该提示中提到的内容，仅在最严重的情况下使用，该操作会导致配置或者数据丢失。
+- 请使用表格描述恰当的内容。请参考[常见问题](/docs/apisix/FAQ#what-is-the-difference-between-plugin-metadata-and-plugin-configs-in-apache-apisix)。
+  - 表格中如果尽量不包含空列和空行。
+  - 表格中的描述需要简洁。
+- 中文与英文、阿拉伯数字之间需要包含一个空格。英文和阿拉伯数字在标点符号前或者标点符号后，不需要加空格。
+- 在 markdown 文件中请使用相对路径而不是绝对路径。
+- 请使用列表使描述更加清晰。
+  - 有序列表：通常用来表示列表之间有前后顺序，例如操作步骤。
+  - 无序列表：无序列表中，各个列表之间属于并列关系，没有先后顺序之分，列表前后需要用空行包围。对于有多项参数或者需要描述的，请使用无序列表。
+- 链接
+  - 链接文本需要有意义。例如“请参考[ApacheAPISIX 官网](https://apisix.apache.org/)”，而不是 “请参考[这里](https://apisix.apache.org/)”
+  - 链接不能裸露。例如：“请参考https://apisix.apache.org”。
+  - 内链请使用相对路径。
+
+### 目录结构
+
+文档的目录如下所示。如果要创建新文档，请选择文档写作时所用语言的 `latest` 文件夹中创建一个新文件。

Review Comment:
   ```suggestion
   目前，Apache APISIX 官网的文档目录如下所示。如果要创建新文档，请选择文档写作时所用语言的 `latest` 文件夹中创建一个新文件。
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-website] SylviaBABY commented on a diff in pull request #1056: docs: update the Chinese Documentation style guide

Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #1056:
URL: https://github.com/apache/apisix-website/pull/1056#discussion_r858162203


##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者，贡献者应遵循此文档以确保文档一致性。
+
+要了解关于贡献的更多信息，请参考 [Contributor Guide](../docs/general/contributor-guide.md)。
+
+## 语气、内容和受众
+
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”。
+- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
+- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话。例如：打满。
+- 不使用侮辱性词汇。例如：“小白”，可更换为“初学者”。
+- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为 Data Plane（数据面）和 Control Plane（控制面）。
+
+## 语言
+
+- 写作时请尽量使用第二人称，如果不适用第二人称可换成其他人称。

Review Comment:
   ```suggestion
   - 写作时请尽量使用第二人称，如果不适用第二人称可统一替换为统称——用户/使用者。
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-website] SylviaBABY commented on a diff in pull request #1056: docs: update the Chinese Documentation style guide

Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #1056:
URL: https://github.com/apache/apisix-website/pull/1056#discussion_r858159805


##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者，贡献者应遵循此文档以确保文档一致性。

Review Comment:
   ```suggestion
   本文档是 Apache APISIX 中文文档的贡献指南，适用于为此网站进行 APISIX 相关的中文文档贡献者，贡献者应遵循本篇写作指南，以确保网站文档的一致性。
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-website] SylviaBABY commented on a diff in pull request #1056: docs: update the Chinese Documentation style guide

Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #1056:
URL: https://github.com/apache/apisix-website/pull/1056#discussion_r858163544


##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者，贡献者应遵循此文档以确保文档一致性。
+
+要了解关于贡献的更多信息，请参考 [Contributor Guide](../docs/general/contributor-guide.md)。
+
+## 语气、内容和受众
+
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”。
+- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
+- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话。例如：打满。
+- 不使用侮辱性词汇。例如：“小白”，可更换为“初学者”。
+- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为 Data Plane（数据面）和 Control Plane（控制面）。
+
+## 语言
+
+- 写作时请尽量使用第二人称，如果不适用第二人称可换成其他人称。
+- 写作时使用主动语态。
+- 句子要求
+  - 避免使用长句。不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，任何情况下都不能接受。
+  - 尽量使用简单句和并列句，避免使用复合句。
+  - 同样一个意思，尽量使用肯定句表达，不使用否定句表达。
+  - 避免使用双重否定句。
+- 请不要在标题、文本、导航或目录中使用`&`代替`和`，`/` 代替 `或`。请参考[一般注意事项](https://developers.google.com/style/accessibility#general-dos-and-donts) 了解更多信息。
+- 对项目特定词汇使用以下拼写：
+  - 在介绍中引用项目和引用项目社区时，使用 Apache APISIX 而不是 APISIX。
+  - 在文档中引用项目时，请使用 APISIX。
+  - APISIX 特定的组件名称，如 Plugin、Route、Service 和 Consumer 等组件名称始终保持首字母大写。
+  - 必要时使用正确的首字母缩略词，例如：
+
+    | ✅              | ❌               |
+    | ---------------- | ---------------- |
+    | URL              | url              |
+    | API              | api              |
+    | APISIX Dashboard | Apisix dashboard |
+    | gRPC             | GRPC/grpc        |
+    | NGINX            | Nginx            |
+

Review Comment:
   ```suggestion
   如不清楚某些词汇到底应该以哪种形态出现，请及时使用搜索引擎进行查询。
   
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-website] SylviaBABY commented on a diff in pull request #1056: docs: update the Chinese Documentation style guide

Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #1056:
URL: https://github.com/apache/apisix-website/pull/1056#discussion_r858161490


##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者，贡献者应遵循此文档以确保文档一致性。
+
+要了解关于贡献的更多信息，请参考 [Contributor Guide](../docs/general/contributor-guide.md)。
+
+## 语气、内容和受众
+
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”。
+- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
+- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话。例如：打满。

Review Comment:
   ```suggestion
   - 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话或互联网词汇。例如：打满。
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-website] SkyeYoung commented on pull request #1056: docs: update the Chinese Documentation style guide

Posted by GitBox <gi...@apache.org>.
SkyeYoung commented on PR #1056:
URL: https://github.com/apache/apisix-website/pull/1056#issuecomment-1110422754

   > I think the question that yilin mentioned really needs to be considered, but at the same time, the official website still needs a Chinese version "style guide". If the underlying website is modified later, then we would modify or update the content related to Docusaurus in this guide.
   
   Hi, I'll try to keep it as consistent as possible with the current format, so stay tuned!
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-website] SylviaBABY commented on a diff in pull request #1056: docs: update the Chinese Documentation style guide

Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #1056:
URL: https://github.com/apache/apisix-website/pull/1056#discussion_r858164521


##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者，贡献者应遵循此文档以确保文档一致性。
+
+要了解关于贡献的更多信息，请参考 [Contributor Guide](../docs/general/contributor-guide.md)。
+
+## 语气、内容和受众
+
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”。
+- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
+- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话。例如：打满。
+- 不使用侮辱性词汇。例如：“小白”，可更换为“初学者”。
+- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为 Data Plane（数据面）和 Control Plane（控制面）。
+
+## 语言
+
+- 写作时请尽量使用第二人称，如果不适用第二人称可换成其他人称。
+- 写作时使用主动语态。
+- 句子要求
+  - 避免使用长句。不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，任何情况下都不能接受。
+  - 尽量使用简单句和并列句，避免使用复合句。
+  - 同样一个意思，尽量使用肯定句表达，不使用否定句表达。
+  - 避免使用双重否定句。
+- 请不要在标题、文本、导航或目录中使用`&`代替`和`，`/` 代替 `或`。请参考[一般注意事项](https://developers.google.com/style/accessibility#general-dos-and-donts) 了解更多信息。
+- 对项目特定词汇使用以下拼写：
+  - 在介绍中引用项目和引用项目社区时，使用 Apache APISIX 而不是 APISIX。
+  - 在文档中引用项目时，请使用 APISIX。
+  - APISIX 特定的组件名称，如 Plugin、Route、Service 和 Consumer 等组件名称始终保持首字母大写。
+  - 必要时使用正确的首字母缩略词，例如：
+
+    | ✅              | ❌               |
+    | ---------------- | ---------------- |
+    | URL              | url              |
+    | API              | api              |
+    | APISIX Dashboard | Apisix dashboard |
+    | gRPC             | GRPC/grpc        |
+    | NGINX            | Nginx            |
+
+## 格式、标点和目录
+
+- 标题和副标题应当是有意义的，可以概括文档内容。
+- 必要时请使用 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`）。在解释代码时使用行高亮提高使用者的注意力。
+    - 代码需要是可执行，建议不要在代码前加上系统自带符号。
+    - 多行多条代码请分别用代码块表示。
+    - 长代码需要进行格式化处理，让用户直观的看到命令全文。
+  - 使用[admonitions](https://docusaurus.io/docs/next/markdown-features/admonitions) 突出显示重要信息。按照以下建议使用它们：
+    - Tip：为用户提供基于其他内容的额外提示。一般可以忽略。
+    - Note：想要突出的一般信息，该信息需要用户关注的。
+    - Important：用户需要关注的一般信息，该信息可能需要用户特别注意。
+    - Warning：用户需要特别关注的信息，该操作可能会导致配置或者数据丢失。
+    - Danger：用户应该非常小心该提示中提到的内容，仅在最严重的情况下使用，该操作会导致配置或者数据丢失。
+- 请使用表格描述恰当的内容。请参考[常见问题](/docs/apisix/FAQ#what-is-the-difference-between-plugin-metadata-and-plugin-configs-in-apache-apisix)。
+  - 表格中如果尽量不包含空列和空行。
+  - 表格中的描述需要简洁。
+- 中文与英文、阿拉伯数字之间需要包含一个空格。英文和阿拉伯数字在标点符号前或者标点符号后，不需要加空格。
+- 在 markdown 文件中请使用相对路径而不是绝对路径。
+- 请使用列表使描述更加清晰。
+  - 有序列表：通常用来表示列表之间有前后顺序，例如操作步骤。
+  - 无序列表：无序列表中，各个列表之间属于并列关系，没有先后顺序之分，列表前后需要用空行包围。对于有多项参数或者需要描述的，请使用无序列表。
+- 链接
+  - 链接文本需要有意义。例如“请参考[ApacheAPISIX 官网](https://apisix.apache.org/)”，而不是 “请参考[这里](https://apisix.apache.org/)”
+  - 链接不能裸露。例如：“请参考https://apisix.apache.org”。

Review Comment:
   ```suggestion
     - 链接不能裸露。例如：“请参考 https://apisix.apache.org”。
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-website] yzeng25 commented on a diff in pull request #1056: docs: update the Chinese Documentation style guide

Posted by GitBox <gi...@apache.org>.
yzeng25 commented on code in PR #1056:
URL: https://github.com/apache/apisix-website/pull/1056#discussion_r858187889


##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者，贡献者应遵循此文档以确保文档一致性。
+
+要了解关于贡献的更多信息，请参考 [Contributor Guide](../docs/general/contributor-guide.md)。
+
+## 语气、内容和受众
+
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”。
+- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
+- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话。例如：打满。
+- 不使用侮辱性词汇。例如：“小白”，可更换为“初学者”。
+- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为 Data Plane（数据面）和 Control Plane（控制面）。
+
+## 语言
+
+- 写作时请尽量使用第二人称，如果不适用第二人称可换成其他人称。
+- 写作时使用主动语态。
+- 句子要求
+  - 避免使用长句。不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，任何情况下都不能接受。
+  - 尽量使用简单句和并列句，避免使用复合句。
+  - 同样一个意思，尽量使用肯定句表达，不使用否定句表达。
+  - 避免使用双重否定句。
+- 请不要在标题、文本、导航或目录中使用`&`代替`和`，`/` 代替 `或`。请参考[一般注意事项](https://developers.google.com/style/accessibility#general-dos-and-donts) 了解更多信息。
+- 对项目特定词汇使用以下拼写：
+  - 在介绍中引用项目和引用项目社区时，使用 Apache APISIX 而不是 APISIX。
+  - 在文档中引用项目时，请使用 APISIX。
+  - APISIX 特定的组件名称，如 Plugin、Route、Service 和 Consumer 等组件名称始终保持首字母大写。
+  - 必要时使用正确的首字母缩略词，例如：
+
+    | ✅              | ❌               |
+    | ---------------- | ---------------- |
+    | URL              | url              |
+    | API              | api              |
+    | APISIX Dashboard | Apisix dashboard |
+    | gRPC             | GRPC/grpc        |
+    | NGINX            | Nginx            |
+
+## 格式、标点和目录
+
+- 标题和副标题应当是有意义的，可以概括文档内容。
+- 必要时请使用 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`）。在解释代码时使用行高亮提高使用者的注意力。
+    - 代码需要是可执行，建议不要在代码前加上系统自带符号。
+    - 多行多条代码请分别用代码块表示。
+    - 长代码需要进行格式化处理，让用户直观的看到命令全文。
+  - 使用[admonitions](https://docusaurus.io/docs/next/markdown-features/admonitions) 突出显示重要信息。按照以下建议使用它们：
+    - Tip：为用户提供基于其他内容的额外提示。一般可以忽略。
+    - Note：想要突出的一般信息，该信息需要用户关注的。
+    - Important：用户需要关注的一般信息，该信息可能需要用户特别注意。
+    - Warning：用户需要特别关注的信息，该操作可能会导致配置或者数据丢失。
+    - Danger：用户应该非常小心该提示中提到的内容，仅在最严重的情况下使用，该操作会导致配置或者数据丢失。
+- 请使用表格描述恰当的内容。请参考[常见问题](/docs/apisix/FAQ#what-is-the-difference-between-plugin-metadata-and-plugin-configs-in-apache-apisix)。
+  - 表格中如果尽量不包含空列和空行。
+  - 表格中的描述需要简洁。
+- 中文与英文、阿拉伯数字之间需要包含一个空格。英文和阿拉伯数字在标点符号前或者标点符号后，不需要加空格。
+- 在 markdown 文件中请使用相对路径而不是绝对路径。
+- 请使用列表使描述更加清晰。
+  - 有序列表：通常用来表示列表之间有前后顺序，例如操作步骤。
+  - 无序列表：无序列表中，各个列表之间属于并列关系，没有先后顺序之分，列表前后需要用空行包围。对于有多项参数或者需要描述的，请使用无序列表。
+- 链接
+  - 链接文本需要有意义。例如“请参考[ApacheAPISIX 官网](https://apisix.apache.org/)”，而不是 “请参考[这里](https://apisix.apache.org/)”

Review Comment:
   Well... pay attention to spaces.
   ```suggestion
     - 链接文本需要有意义。例如“请参考 [Apache APISIX 官网](https://apisix.apache.org/)”，而不是 “请参考[这里](https://apisix.apache.org/)”
   ```



##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者，贡献者应遵循此文档以确保文档一致性。
+
+要了解关于贡献的更多信息，请参考 [Contributor Guide](../docs/general/contributor-guide.md)。
+
+## 语气、内容和受众
+
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”。
+- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
+- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话。例如：打满。
+- 不使用侮辱性词汇。例如：“小白”，可更换为“初学者”。
+- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为 Data Plane（数据面）和 Control Plane（控制面）。
+
+## 语言
+
+- 写作时请尽量使用第二人称，如果不适用第二人称可换成其他人称。
+- 写作时使用主动语态。
+- 句子要求
+  - 避免使用长句。不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，任何情况下都不能接受。
+  - 尽量使用简单句和并列句，避免使用复合句。
+  - 同样一个意思，尽量使用肯定句表达，不使用否定句表达。
+  - 避免使用双重否定句。
+- 请不要在标题、文本、导航或目录中使用`&`代替`和`，`/` 代替 `或`。请参考[一般注意事项](https://developers.google.com/style/accessibility#general-dos-and-donts) 了解更多信息。
+- 对项目特定词汇使用以下拼写：
+  - 在介绍中引用项目和引用项目社区时，使用 Apache APISIX 而不是 APISIX。
+  - 在文档中引用项目时，请使用 APISIX。
+  - APISIX 特定的组件名称，如 Plugin、Route、Service 和 Consumer 等组件名称始终保持首字母大写。
+  - 必要时使用正确的首字母缩略词，例如：
+
+    | ✅              | ❌               |
+    | ---------------- | ---------------- |
+    | URL              | url              |
+    | API              | api              |
+    | APISIX Dashboard | Apisix dashboard |
+    | gRPC             | GRPC/grpc        |
+    | NGINX            | Nginx            |
+
+## 格式、标点和目录
+
+- 标题和副标题应当是有意义的，可以概括文档内容。
+- 必要时请使用 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`）。在解释代码时使用行高亮提高使用者的注意力。
+    - 代码需要是可执行，建议不要在代码前加上系统自带符号。
+    - 多行多条代码请分别用代码块表示。
+    - 长代码需要进行格式化处理，让用户直观的看到命令全文。
+  - 使用[admonitions](https://docusaurus.io/docs/next/markdown-features/admonitions) 突出显示重要信息。按照以下建议使用它们：
+    - Tip：为用户提供基于其他内容的额外提示。一般可以忽略。
+    - Note：想要突出的一般信息，该信息需要用户关注的。
+    - Important：用户需要关注的一般信息，该信息可能需要用户特别注意。
+    - Warning：用户需要特别关注的信息，该操作可能会导致配置或者数据丢失。
+    - Danger：用户应该非常小心该提示中提到的内容，仅在最严重的情况下使用，该操作会导致配置或者数据丢失。
+- 请使用表格描述恰当的内容。请参考[常见问题](/docs/apisix/FAQ#what-is-the-difference-between-plugin-metadata-and-plugin-configs-in-apache-apisix)。
+  - 表格中如果尽量不包含空列和空行。
+  - 表格中的描述需要简洁。
+- 中文与英文、阿拉伯数字之间需要包含一个空格。英文和阿拉伯数字在标点符号前或者标点符号后，不需要加空格。

Review Comment:
   Add some examples could be clearer.
   ```suggestion
   - 中文与英文、阿拉伯数字之间需要包含一个空格。英文和阿拉伯数字在标点符号前或者标点符号后，不需要加空格。
       - Example 1：
       - Example 2：
       - Example 3：
   ```



##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者，贡献者应遵循此文档以确保文档一致性。
+
+要了解关于贡献的更多信息，请参考 [Contributor Guide](../docs/general/contributor-guide.md)。
+
+## 语气、内容和受众
+
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”。
+- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
+- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话。例如：打满。
+- 不使用侮辱性词汇。例如：“小白”，可更换为“初学者”。
+- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为 Data Plane（数据面）和 Control Plane（控制面）。
+
+## 语言
+
+- 写作时请尽量使用第二人称，如果不适用第二人称可换成其他人称。
+- 写作时使用主动语态。
+- 句子要求
+  - 避免使用长句。不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，任何情况下都不能接受。
+  - 尽量使用简单句和并列句，避免使用复合句。
+  - 同样一个意思，尽量使用肯定句表达，不使用否定句表达。
+  - 避免使用双重否定句。
+- 请不要在标题、文本、导航或目录中使用`&`代替`和`，`/` 代替 `或`。请参考[一般注意事项](https://developers.google.com/style/accessibility#general-dos-and-donts) 了解更多信息。

Review Comment:
   ```suggestion
   - 请不要在标题、文本、导航或目录中使用 `&` 代替`和`，`/` 代替 `或`。请参考[一般注意事项](https://developers.google.com/style/accessibility#general-dos-and-donts) 了解更多信息。
   ```



##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者，贡献者应遵循此文档以确保文档一致性。
+
+要了解关于贡献的更多信息，请参考 [Contributor Guide](../docs/general/contributor-guide.md)。
+
+## 语气、内容和受众
+
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”。
+- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
+- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话。例如：打满。
+- 不使用侮辱性词汇。例如：“小白”，可更换为“初学者”。
+- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为 Data Plane（数据面）和 Control Plane（控制面）。

Review Comment:
   ```suggestion
   - 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为 数据面（Data Plane，简称 DP）和控制面（Control Plane，简称 CP）。
   ```



##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.

Review Comment:
   ```suggestion
   description: Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者。
   ```



##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者，贡献者应遵循此文档以确保文档一致性。
+
+要了解关于贡献的更多信息，请参考 [Contributor Guide](../docs/general/contributor-guide.md)。
+
+## 语气、内容和受众
+
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”。
+- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
+- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话。例如：打满。
+- 不使用侮辱性词汇。例如：“小白”，可更换为“初学者”。
+- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为 Data Plane（数据面）和 Control Plane（控制面）。
+
+## 语言
+
+- 写作时请尽量使用第二人称，如果不适用第二人称可换成其他人称。
+- 写作时使用主动语态。
+- 句子要求
+  - 避免使用长句。不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，任何情况下都不能接受。
+  - 尽量使用简单句和并列句，避免使用复合句。
+  - 同样一个意思，尽量使用肯定句表达，不使用否定句表达。
+  - 避免使用双重否定句。
+- 请不要在标题、文本、导航或目录中使用`&`代替`和`，`/` 代替 `或`。请参考[一般注意事项](https://developers.google.com/style/accessibility#general-dos-and-donts) 了解更多信息。
+- 对项目特定词汇使用以下拼写：
+  - 在介绍中引用项目和引用项目社区时，使用 Apache APISIX 而不是 APISIX。
+  - 在文档中引用项目时，请使用 APISIX。
+  - APISIX 特定的组件名称，如 Plugin、Route、Service 和 Consumer 等组件名称始终保持首字母大写。
+  - 必要时使用正确的首字母缩略词，例如：
+
+    | ✅              | ❌               |
+    | ---------------- | ---------------- |
+    | URL              | url              |
+    | API              | api              |
+    | APISIX Dashboard | Apisix dashboard |
+    | gRPC             | GRPC/grpc        |
+    | NGINX            | Nginx            |
+
+## 格式、标点和目录
+
+- 标题和副标题应当是有意义的，可以概括文档内容。
+- 必要时请使用 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`）。在解释代码时使用行高亮提高使用者的注意力。
+    - 代码需要是可执行，建议不要在代码前加上系统自带符号。

Review Comment:
   ```suggestion
       - 代码是可执行的，不要在代码前加上系统自带符号，例如 `$ cd Desktop` 应修改为 `cd Desktop`。
   ```



##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者，贡献者应遵循此文档以确保文档一致性。
+
+要了解关于贡献的更多信息，请参考 [Contributor Guide](../docs/general/contributor-guide.md)。
+
+## 语气、内容和受众
+
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”。
+- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
+- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话。例如：打满。
+- 不使用侮辱性词汇。例如：“小白”，可更换为“初学者”。
+- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为 Data Plane（数据面）和 Control Plane（控制面）。
+
+## 语言
+
+- 写作时请尽量使用第二人称，如果不适用第二人称可换成其他人称。
+- 写作时使用主动语态。
+- 句子要求
+  - 避免使用长句。不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，任何情况下都不能接受。
+  - 尽量使用简单句和并列句，避免使用复合句。
+  - 同样一个意思，尽量使用肯定句表达，不使用否定句表达。
+  - 避免使用双重否定句。
+- 请不要在标题、文本、导航或目录中使用`&`代替`和`，`/` 代替 `或`。请参考[一般注意事项](https://developers.google.com/style/accessibility#general-dos-and-donts) 了解更多信息。
+- 对项目特定词汇使用以下拼写：
+  - 在介绍中引用项目和引用项目社区时，使用 Apache APISIX 而不是 APISIX。
+  - 在文档中引用项目时，请使用 APISIX。
+  - APISIX 特定的组件名称，如 Plugin、Route、Service 和 Consumer 等组件名称始终保持首字母大写。
+  - 必要时使用正确的首字母缩略词，例如：
+
+    | ✅              | ❌               |
+    | ---------------- | ---------------- |
+    | URL              | url              |
+    | API              | api              |
+    | APISIX Dashboard | Apisix dashboard |
+    | gRPC             | GRPC/grpc        |
+    | NGINX            | Nginx            |
+
+## 格式、标点和目录
+
+- 标题和副标题应当是有意义的，可以概括文档内容。
+- 必要时请使用 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`）。在解释代码时使用行高亮提高使用者的注意力。
+    - 代码需要是可执行，建议不要在代码前加上系统自带符号。
+    - 多行多条代码请分别用代码块表示。
+    - 长代码需要进行格式化处理，让用户直观的看到命令全文。
+  - 使用[admonitions](https://docusaurus.io/docs/next/markdown-features/admonitions) 突出显示重要信息。按照以下建议使用它们：
+    - Tip：为用户提供基于其他内容的额外提示。一般可以忽略。
+    - Note：想要突出的一般信息，该信息需要用户关注的。
+    - Important：用户需要关注的一般信息，该信息可能需要用户特别注意。
+    - Warning：用户需要特别关注的信息，该操作可能会导致配置或者数据丢失。
+    - Danger：用户应该非常小心该提示中提到的内容，仅在最严重的情况下使用，该操作会导致配置或者数据丢失。
+- 请使用表格描述恰当的内容。请参考[常见问题](/docs/apisix/FAQ#what-is-the-difference-between-plugin-metadata-and-plugin-configs-in-apache-apisix)。
+  - 表格中如果尽量不包含空列和空行。
+  - 表格中的描述需要简洁。
+- 中文与英文、阿拉伯数字之间需要包含一个空格。英文和阿拉伯数字在标点符号前或者标点符号后，不需要加空格。
+- 在 markdown 文件中请使用相对路径而不是绝对路径。
+- 请使用列表使描述更加清晰。
+  - 有序列表：通常用来表示列表之间有前后顺序，例如操作步骤。
+  - 无序列表：无序列表中，各个列表之间属于并列关系，没有先后顺序之分，列表前后需要用空行包围。对于有多项参数或者需要描述的，请使用无序列表。
+- 链接
+  - 链接文本需要有意义。例如“请参考[ApacheAPISIX 官网](https://apisix.apache.org/)”，而不是 “请参考[这里](https://apisix.apache.org/)”
+  - 链接不能裸露。例如：“请参考https://apisix.apache.org”。
+  - 内链请使用相对路径。
+
+### 目录结构
+
+文档的目录如下所示。如果要创建新文档，请选择文档写作时所用语言的 `latest` 文件夹中创建一个新文件。
+
+```text
+/docs
+├── assets
+│   ├── images
+│   │   ├── xxxxx.png
+│   └── other
+│       └── xxxxx.xxx
+├── en
+│   └── latest
+│       ├── doc1.md
+│       └── folder
+│           └── doc2.md
+│               └── folder2
+│                   └── doc3.md
+│
+└── zh
+    └── latest
+        └── ...

Review Comment:
   Since this doc is for zh-cn users, I think explanations of the zh-cn doc structure is more appropriate.  
   ```suggestion
   ├── en
   │
   └── zh
       └── latest
           ├── doc1.md
   │       └── folder
   │           └── doc2.md
   │               └── folder2
   │                   └── doc3.md
   │
   ```



##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者，贡献者应遵循此文档以确保文档一致性。
+
+要了解关于贡献的更多信息，请参考 [Contributor Guide](../docs/general/contributor-guide.md)。
+
+## 语气、内容和受众
+
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”。
+- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
+- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话。例如：打满。
+- 不使用侮辱性词汇。例如：“小白”，可更换为“初学者”。
+- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为 Data Plane（数据面）和 Control Plane（控制面）。
+
+## 语言
+
+- 写作时请尽量使用第二人称，如果不适用第二人称可换成其他人称。
+- 写作时使用主动语态。
+- 句子要求
+  - 避免使用长句。不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，任何情况下都不能接受。
+  - 尽量使用简单句和并列句，避免使用复合句。
+  - 同样一个意思，尽量使用肯定句表达，不使用否定句表达。
+  - 避免使用双重否定句。
+- 请不要在标题、文本、导航或目录中使用`&`代替`和`，`/` 代替 `或`。请参考[一般注意事项](https://developers.google.com/style/accessibility#general-dos-and-donts) 了解更多信息。
+- 对项目特定词汇使用以下拼写：
+  - 在介绍中引用项目和引用项目社区时，使用 Apache APISIX 而不是 APISIX。
+  - 在文档中引用项目时，请使用 APISIX。
+  - APISIX 特定的组件名称，如 Plugin、Route、Service 和 Consumer 等组件名称始终保持首字母大写。
+  - 必要时使用正确的首字母缩略词，例如：
+
+    | ✅              | ❌               |
+    | ---------------- | ---------------- |
+    | URL              | url              |
+    | API              | api              |
+    | APISIX Dashboard | Apisix dashboard |
+    | gRPC             | GRPC/grpc        |
+    | NGINX            | Nginx            |
+
+## 格式、标点和目录
+
+- 标题和副标题应当是有意义的，可以概括文档内容。
+- 必要时请使用 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`）。在解释代码时使用行高亮提高使用者的注意力。
+    - 代码需要是可执行，建议不要在代码前加上系统自带符号。
+    - 多行多条代码请分别用代码块表示。
+    - 长代码需要进行格式化处理，让用户直观的看到命令全文。
+  - 使用[admonitions](https://docusaurus.io/docs/next/markdown-features/admonitions) 突出显示重要信息。按照以下建议使用它们：

Review Comment:
   ```suggestion
     - 使用 [admonitions](https://docusaurus.io/docs/next/markdown-features/admonitions) 突出显示重要信息。以下是每个 admonitions 的使用场景：
   ```



##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者，贡献者应遵循此文档以确保文档一致性。
+
+要了解关于贡献的更多信息，请参考 [Contributor Guide](../docs/general/contributor-guide.md)。
+
+## 语气、内容和受众
+
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”。
+- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
+- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话。例如：打满。
+- 不使用侮辱性词汇。例如：“小白”，可更换为“初学者”。
+- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为 Data Plane（数据面）和 Control Plane（控制面）。
+
+## 语言
+
+- 写作时请尽量使用第二人称，如果不适用第二人称可换成其他人称。
+- 写作时使用主动语态。
+- 句子要求
+  - 避免使用长句。不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，任何情况下都不能接受。
+  - 尽量使用简单句和并列句，避免使用复合句。
+  - 同样一个意思，尽量使用肯定句表达，不使用否定句表达。
+  - 避免使用双重否定句。
+- 请不要在标题、文本、导航或目录中使用`&`代替`和`，`/` 代替 `或`。请参考[一般注意事项](https://developers.google.com/style/accessibility#general-dos-and-donts) 了解更多信息。
+- 对项目特定词汇使用以下拼写：
+  - 在介绍中引用项目和引用项目社区时，使用 Apache APISIX 而不是 APISIX。
+  - 在文档中引用项目时，请使用 APISIX。
+  - APISIX 特定的组件名称，如 Plugin、Route、Service 和 Consumer 等组件名称始终保持首字母大写。
+  - 必要时使用正确的首字母缩略词，例如：
+
+    | ✅              | ❌               |
+    | ---------------- | ---------------- |
+    | URL              | url              |
+    | API              | api              |
+    | APISIX Dashboard | Apisix dashboard |
+    | gRPC             | GRPC/grpc        |
+    | NGINX            | Nginx            |
+
+## 格式、标点和目录
+
+- 标题和副标题应当是有意义的，可以概括文档内容。
+- 必要时请使用 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`）。在解释代码时使用行高亮提高使用者的注意力。
+    - 代码需要是可执行，建议不要在代码前加上系统自带符号。
+    - 多行多条代码请分别用代码块表示。
+    - 长代码需要进行格式化处理，让用户直观的看到命令全文。

Review Comment:
   ```suggestion
       - 长代码需要进行格式化处理，让用户直观地看到命令全文。
   ```



##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations

Review Comment:
   ```suggestion
     - API 网关
     - APISIX
     - Apache APISIX
     - 中文文档写作指南
   ```



##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者，贡献者应遵循此文档以确保文档一致性。
+
+要了解关于贡献的更多信息，请参考 [Contributor Guide](../docs/general/contributor-guide.md)。
+
+## 语气、内容和受众
+
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”。
+- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
+- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话。例如：打满。
+- 不使用侮辱性词汇。例如：“小白”，可更换为“初学者”。
+- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为 Data Plane（数据面）和 Control Plane（控制面）。
+
+## 语言
+
+- 写作时请尽量使用第二人称，如果不适用第二人称可换成其他人称。
+- 写作时使用主动语态。
+- 句子要求
+  - 避免使用长句。不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，任何情况下都不能接受。
+  - 尽量使用简单句和并列句，避免使用复合句。
+  - 同样一个意思，尽量使用肯定句表达，不使用否定句表达。
+  - 避免使用双重否定句。
+- 请不要在标题、文本、导航或目录中使用`&`代替`和`，`/` 代替 `或`。请参考[一般注意事项](https://developers.google.com/style/accessibility#general-dos-and-donts) 了解更多信息。
+- 对项目特定词汇使用以下拼写：
+  - 在介绍中引用项目和引用项目社区时，使用 Apache APISIX 而不是 APISIX。
+  - 在文档中引用项目时，请使用 APISIX。
+  - APISIX 特定的组件名称，如 Plugin、Route、Service 和 Consumer 等组件名称始终保持首字母大写。
+  - 必要时使用正确的首字母缩略词，例如：
+
+    | ✅              | ❌               |
+    | ---------------- | ---------------- |
+    | URL              | url              |
+    | API              | api              |
+    | APISIX Dashboard | Apisix dashboard |
+    | gRPC             | GRPC/grpc        |
+    | NGINX            | Nginx            |
+
+## 格式、标点和目录
+
+- 标题和副标题应当是有意义的，可以概括文档内容。
+- 必要时请使用 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`）。在解释代码时使用行高亮提高使用者的注意力。
+    - 代码需要是可执行，建议不要在代码前加上系统自带符号。
+    - 多行多条代码请分别用代码块表示。
+    - 长代码需要进行格式化处理，让用户直观的看到命令全文。
+  - 使用[admonitions](https://docusaurus.io/docs/next/markdown-features/admonitions) 突出显示重要信息。按照以下建议使用它们：
+    - Tip：为用户提供基于其他内容的额外提示。一般可以忽略。
+    - Note：想要突出的一般信息，该信息需要用户关注的。
+    - Important：用户需要关注的一般信息，该信息可能需要用户特别注意。
+    - Warning：用户需要特别关注的信息，该操作可能会导致配置或者数据丢失。
+    - Danger：用户应该非常小心该提示中提到的内容，仅在最严重的情况下使用，该操作会导致配置或者数据丢失。
+- 请使用表格描述恰当的内容。请参考[常见问题](/docs/apisix/FAQ#what-is-the-difference-between-plugin-metadata-and-plugin-configs-in-apache-apisix)。
+  - 表格中如果尽量不包含空列和空行。

Review Comment:
   Doesn't make sense, need to modify this sentence.
   ```suggestion
     - 请尽量保证表格内容不包含空置的行和列。
   ```



##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者，贡献者应遵循此文档以确保文档一致性。
+
+要了解关于贡献的更多信息，请参考 [Contributor Guide](../docs/general/contributor-guide.md)。
+
+## 语气、内容和受众
+
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”。
+- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
+- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话。例如：打满。
+- 不使用侮辱性词汇。例如：“小白”，可更换为“初学者”。
+- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为 Data Plane（数据面）和 Control Plane（控制面）。
+
+## 语言
+
+- 写作时请尽量使用第二人称，如果不适用第二人称可换成其他人称。
+- 写作时使用主动语态。
+- 句子要求
+  - 避免使用长句。不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，任何情况下都不能接受。
+  - 尽量使用简单句和并列句，避免使用复合句。
+  - 同样一个意思，尽量使用肯定句表达，不使用否定句表达。
+  - 避免使用双重否定句。
+- 请不要在标题、文本、导航或目录中使用`&`代替`和`，`/` 代替 `或`。请参考[一般注意事项](https://developers.google.com/style/accessibility#general-dos-and-donts) 了解更多信息。
+- 对项目特定词汇使用以下拼写：
+  - 在介绍中引用项目和引用项目社区时，使用 Apache APISIX 而不是 APISIX。
+  - 在文档中引用项目时，请使用 APISIX。
+  - APISIX 特定的组件名称，如 Plugin、Route、Service 和 Consumer 等组件名称始终保持首字母大写。
+  - 必要时使用正确的首字母缩略词，例如：
+
+    | ✅              | ❌               |
+    | ---------------- | ---------------- |
+    | URL              | url              |
+    | API              | api              |
+    | APISIX Dashboard | Apisix dashboard |
+    | gRPC             | GRPC/grpc        |
+    | NGINX            | Nginx            |
+
+## 格式、标点和目录
+
+- 标题和副标题应当是有意义的，可以概括文档内容。
+- 必要时请使用 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`）。在解释代码时使用行高亮提高使用者的注意力。
+    - 代码需要是可执行，建议不要在代码前加上系统自带符号。
+    - 多行多条代码请分别用代码块表示。
+    - 长代码需要进行格式化处理，让用户直观的看到命令全文。
+  - 使用[admonitions](https://docusaurus.io/docs/next/markdown-features/admonitions) 突出显示重要信息。按照以下建议使用它们：
+    - Tip：为用户提供基于其他内容的额外提示。一般可以忽略。
+    - Note：想要突出的一般信息，该信息需要用户关注的。
+    - Important：用户需要关注的一般信息，该信息可能需要用户特别注意。
+    - Warning：用户需要特别关注的信息，该操作可能会导致配置或者数据丢失。
+    - Danger：用户应该非常小心该提示中提到的内容，仅在最严重的情况下使用，该操作会导致配置或者数据丢失。
+- 请使用表格描述恰当的内容。请参考[常见问题](/docs/apisix/FAQ#what-is-the-difference-between-plugin-metadata-and-plugin-configs-in-apache-apisix)。
+  - 表格中如果尽量不包含空列和空行。
+  - 表格中的描述需要简洁。
+- 中文与英文、阿拉伯数字之间需要包含一个空格。英文和阿拉伯数字在标点符号前或者标点符号后，不需要加空格。
+- 在 markdown 文件中请使用相对路径而不是绝对路径。
+- 请使用列表使描述更加清晰。
+  - 有序列表：通常用来表示列表之间有前后顺序，例如操作步骤。
+  - 无序列表：无序列表中，各个列表之间属于并列关系，没有先后顺序之分，列表前后需要用空行包围。对于有多项参数或者需要描述的，请使用无序列表。
+- 链接
+  - 链接文本需要有意义。例如“请参考[ApacheAPISIX 官网](https://apisix.apache.org/)”，而不是 “请参考[这里](https://apisix.apache.org/)”
+  - 链接不能裸露。例如：“请参考https://apisix.apache.org”。

Review Comment:
   ditto, you need to pay attention to spaces.
   ```suggestion
     - 链接不能裸露。例如：“请参考 https://apisix.apache.org”。
   ```



##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者，贡献者应遵循此文档以确保文档一致性。
+
+要了解关于贡献的更多信息，请参考 [Contributor Guide](../docs/general/contributor-guide.md)。
+
+## 语气、内容和受众
+
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”。
+- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
+- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话。例如：打满。
+- 不使用侮辱性词汇。例如：“小白”，可更换为“初学者”。

Review Comment:
   ```suggestion
   - 不使用具有歧义的词汇。例如：“小白”，可更换为“初学者”。
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-website] SylviaBABY commented on a diff in pull request #1056: docs: update the Chinese Documentation style guide

Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #1056:
URL: https://github.com/apache/apisix-website/pull/1056#discussion_r858163107


##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者，贡献者应遵循此文档以确保文档一致性。
+
+要了解关于贡献的更多信息，请参考 [Contributor Guide](../docs/general/contributor-guide.md)。
+
+## 语气、内容和受众
+
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”。
+- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
+- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话。例如：打满。
+- 不使用侮辱性词汇。例如：“小白”，可更换为“初学者”。
+- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为 Data Plane（数据面）和 Control Plane（控制面）。
+
+## 语言
+
+- 写作时请尽量使用第二人称，如果不适用第二人称可换成其他人称。
+- 写作时使用主动语态。
+- 句子要求
+  - 避免使用长句。不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，任何情况下都不能接受。
+  - 尽量使用简单句和并列句，避免使用复合句。
+  - 同样一个意思，尽量使用肯定句表达，不使用否定句表达。
+  - 避免使用双重否定句。
+- 请不要在标题、文本、导航或目录中使用`&`代替`和`，`/` 代替 `或`。请参考[一般注意事项](https://developers.google.com/style/accessibility#general-dos-and-donts) 了解更多信息。

Review Comment:
   ```suggestion
   - 请不要在标题、文本、导航或目录中使用`&`和`/`，使用`和``或`进行代替即可。请参考[一般注意事项](https://developers.google.com/style/accessibility#general-dos-and-donts) 了解更多信息。
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-website] yzeng25 commented on pull request #1056: docs: update the Chinese Documentation style guide

Posted by GitBox <gi...@apache.org>.
yzeng25 commented on PR #1056:
URL: https://github.com/apache/apisix-website/pull/1056#issuecomment-1109258288

   Another thought: Is it a really urgent thing to do? I see discussions of changing the website from Docusaurus to Hexo or Hugo in June. How much of this article is applicable after framework is changed? How much extra work is needed after the change?


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-website] hf400159 commented on pull request #1056: docs: update the Chinese Documentation style guide

Posted by GitBox <gi...@apache.org>.
hf400159 commented on PR #1056:
URL: https://github.com/apache/apisix-website/pull/1056#issuecomment-1109423742

   > Another thought: Is it a really urgent thing to do? I see discussions of changing the website from Docusaurus to Hexo or Hugo in June. How much of this article is applicable after framework is changed? How much extra work is needed after the change?
   
   Much of the documentation style is platform-independent and may require changes to advanced features of Docusaurus. Anyway, make sure there is content first, if it is changed to Hexo or Hugo I can modify it.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-website] SylviaBABY commented on a diff in pull request #1056: docs: update the Chinese Documentation style guide

Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #1056:
URL: https://github.com/apache/apisix-website/pull/1056#discussion_r858160700


##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者，贡献者应遵循此文档以确保文档一致性。
+
+要了解关于贡献的更多信息，请参考 [Contributor Guide](../docs/general/contributor-guide.md)。
+
+## 语气、内容和受众
+
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”。

Review Comment:
   ```suggestion
   - 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”或着直接用“用户需要”等统称。
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-website] SylviaBABY commented on pull request #1056: docs: update the Chinese Documentation style guide

Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on PR #1056:
URL: https://github.com/apache/apisix-website/pull/1056#issuecomment-1109420573

   LGTM
   
   I think the question that yilin mentioned really needs to be considered, but at the same time, the official website still needs a Chinese version "style guide". If the underlying website is modified later, then we would modify or update the content related to Docusaurus in this guide.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-website] yzeng25 commented on a diff in pull request #1056: docs: update the Chinese Documentation style guide

Posted by GitBox <gi...@apache.org>.
yzeng25 commented on code in PR #1056:
URL: https://github.com/apache/apisix-website/pull/1056#discussion_r858202425


##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者，贡献者应遵循此文档以确保文档一致性。
+
+要了解关于贡献的更多信息，请参考 [Contributor Guide](../docs/general/contributor-guide.md)。

Review Comment:
   ```suggestion
   要了解关于贡献的更多信息，请参考 [代码贡献流程](../docs/general/contributor-guide.md)。
   ```



##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者，贡献者应遵循此文档以确保文档一致性。
+
+要了解关于贡献的更多信息，请参考 [Contributor Guide](../docs/general/contributor-guide.md)。
+
+## 语气、内容和受众
+
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”。
+- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
+- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话。例如：打满。
+- 不使用侮辱性词汇。例如：“小白”，可更换为“初学者”。
+- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为 Data Plane（数据面）和 Control Plane（控制面）。
+
+## 语言
+
+- 写作时请尽量使用第二人称，如果不适用第二人称可换成其他人称。
+- 写作时使用主动语态。
+- 句子要求
+  - 避免使用长句。不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，任何情况下都不能接受。
+  - 尽量使用简单句和并列句，避免使用复合句。
+  - 同样一个意思，尽量使用肯定句表达，不使用否定句表达。
+  - 避免使用双重否定句。
+- 请不要在标题、文本、导航或目录中使用`&`代替`和`，`/` 代替 `或`。请参考[一般注意事项](https://developers.google.com/style/accessibility#general-dos-and-donts) 了解更多信息。
+- 对项目特定词汇使用以下拼写：
+  - 在介绍中引用项目和引用项目社区时，使用 Apache APISIX 而不是 APISIX。
+  - 在文档中引用项目时，请使用 APISIX。
+  - APISIX 特定的组件名称，如 Plugin、Route、Service 和 Consumer 等组件名称始终保持首字母大写。
+  - 必要时使用正确的首字母缩略词，例如：
+
+    | ✅              | ❌               |
+    | ---------------- | ---------------- |
+    | URL              | url              |
+    | API              | api              |
+    | APISIX Dashboard | Apisix dashboard |
+    | gRPC             | GRPC/grpc        |
+    | NGINX            | Nginx            |
+
+## 格式、标点和目录
+
+- 标题和副标题应当是有意义的，可以概括文档内容。
+- 必要时请使用 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`）。在解释代码时使用行高亮提高使用者的注意力。
+    - 代码需要是可执行，建议不要在代码前加上系统自带符号。
+    - 多行多条代码请分别用代码块表示。
+    - 长代码需要进行格式化处理，让用户直观的看到命令全文。
+  - 使用[admonitions](https://docusaurus.io/docs/next/markdown-features/admonitions) 突出显示重要信息。按照以下建议使用它们：
+    - Tip：为用户提供基于其他内容的额外提示。一般可以忽略。
+    - Note：想要突出的一般信息，该信息需要用户关注的。
+    - Important：用户需要关注的一般信息，该信息可能需要用户特别注意。
+    - Warning：用户需要特别关注的信息，该操作可能会导致配置或者数据丢失。
+    - Danger：用户应该非常小心该提示中提到的内容，仅在最严重的情况下使用，该操作会导致配置或者数据丢失。
+- 请使用表格描述恰当的内容。请参考[常见问题](/docs/apisix/FAQ#what-is-the-difference-between-plugin-metadata-and-plugin-configs-in-apache-apisix)。
+  - 表格中如果尽量不包含空列和空行。
+  - 表格中的描述需要简洁。
+- 中文与英文、阿拉伯数字之间需要包含一个空格。英文和阿拉伯数字在标点符号前或者标点符号后，不需要加空格。
+- 在 markdown 文件中请使用相对路径而不是绝对路径。
+- 请使用列表使描述更加清晰。
+  - 有序列表：通常用来表示列表之间有前后顺序，例如操作步骤。
+  - 无序列表：无序列表中，各个列表之间属于并列关系，没有先后顺序之分，列表前后需要用空行包围。对于有多项参数或者需要描述的，请使用无序列表。
+- 链接
+  - 链接文本需要有意义。例如“请参考[ApacheAPISIX 官网](https://apisix.apache.org/)”，而不是 “请参考[这里](https://apisix.apache.org/)”
+  - 链接不能裸露。例如：“请参考https://apisix.apache.org”。
+  - 内链请使用相对路径。
+
+### 目录结构
+
+文档的目录如下所示。如果要创建新文档，请选择文档写作时所用语言的 `latest` 文件夹中创建一个新文件。
+
+```text
+/docs
+├── assets
+│   ├── images
+│   │   ├── xxxxx.png
+│   └── other
+│       └── xxxxx.xxx
+├── en
+│   └── latest
+│       ├── doc1.md
+│       └── folder
+│           └── doc2.md
+│               └── folder2
+│                   └── doc3.md
+│
+└── zh
+    └── latest
+        └── ...
+```
+
+### 配置文件
+
+配置文件位于 `/docs/<locale>/latest/config.json` 中，其中 locale 表示区域设置代码（语言）。有关详细信息，请参考[本地语言](https://www.science.co.il/language/Locale-codes.php)。请注意，语言环境全部都是小写。
+
+您可以从 [Docusaurus 文档](https://v2.docusaurus.io/docs/next/sidebar)中了解有关侧边栏的更多信息。
+
+```json
+{
+  "version": 2.3,
+  "sidebar": [
+    // The left sidebar of the APISIX website
+    {
+      "type": "doc",
+      "id": "doc2" // id is the filename of the md file
+    },
+    {
+      "type": "category", // category is a collapsed column, nestable
+      "label": "folder",
+      "items": [
+        {
+          "type": "doc",
+          "id": "folder/doc2"
+        },
+        {
+          "type": "category",
+          "label": "folder2",
+          "items": [
+            "folder2/doc3"
+          ]
+        }
+      ]
+    },
+    {
+      "type": "link",
+      "label": "CHANGELOG",
+      "href": "https://github.com/apache/apisix/blob/master/CHANGELOG"
+    }
+  ]
+}
+```
+
+## 图片和嵌入内容

Review Comment:
   ```suggestion
   ## 为你的文章添加图片
   ```



##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者，贡献者应遵循此文档以确保文档一致性。
+
+要了解关于贡献的更多信息，请参考 [Contributor Guide](../docs/general/contributor-guide.md)。
+
+## 语气、内容和受众
+
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”。
+- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
+- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话。例如：打满。
+- 不使用侮辱性词汇。例如：“小白”，可更换为“初学者”。
+- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为 Data Plane（数据面）和 Control Plane（控制面）。
+
+## 语言
+
+- 写作时请尽量使用第二人称，如果不适用第二人称可换成其他人称。
+- 写作时使用主动语态。
+- 句子要求
+  - 避免使用长句。不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，任何情况下都不能接受。
+  - 尽量使用简单句和并列句，避免使用复合句。
+  - 同样一个意思，尽量使用肯定句表达，不使用否定句表达。
+  - 避免使用双重否定句。
+- 请不要在标题、文本、导航或目录中使用`&`代替`和`，`/` 代替 `或`。请参考[一般注意事项](https://developers.google.com/style/accessibility#general-dos-and-donts) 了解更多信息。
+- 对项目特定词汇使用以下拼写：
+  - 在介绍中引用项目和引用项目社区时，使用 Apache APISIX 而不是 APISIX。
+  - 在文档中引用项目时，请使用 APISIX。
+  - APISIX 特定的组件名称，如 Plugin、Route、Service 和 Consumer 等组件名称始终保持首字母大写。
+  - 必要时使用正确的首字母缩略词，例如：
+
+    | ✅              | ❌               |
+    | ---------------- | ---------------- |
+    | URL              | url              |
+    | API              | api              |
+    | APISIX Dashboard | Apisix dashboard |
+    | gRPC             | GRPC/grpc        |
+    | NGINX            | Nginx            |
+
+## 格式、标点和目录
+
+- 标题和副标题应当是有意义的，可以概括文档内容。
+- 必要时请使用 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`）。在解释代码时使用行高亮提高使用者的注意力。
+    - 代码需要是可执行，建议不要在代码前加上系统自带符号。
+    - 多行多条代码请分别用代码块表示。
+    - 长代码需要进行格式化处理，让用户直观的看到命令全文。
+  - 使用[admonitions](https://docusaurus.io/docs/next/markdown-features/admonitions) 突出显示重要信息。按照以下建议使用它们：
+    - Tip：为用户提供基于其他内容的额外提示。一般可以忽略。
+    - Note：想要突出的一般信息，该信息需要用户关注的。
+    - Important：用户需要关注的一般信息，该信息可能需要用户特别注意。
+    - Warning：用户需要特别关注的信息，该操作可能会导致配置或者数据丢失。
+    - Danger：用户应该非常小心该提示中提到的内容，仅在最严重的情况下使用，该操作会导致配置或者数据丢失。
+- 请使用表格描述恰当的内容。请参考[常见问题](/docs/apisix/FAQ#what-is-the-difference-between-plugin-metadata-and-plugin-configs-in-apache-apisix)。
+  - 表格中如果尽量不包含空列和空行。
+  - 表格中的描述需要简洁。
+- 中文与英文、阿拉伯数字之间需要包含一个空格。英文和阿拉伯数字在标点符号前或者标点符号后，不需要加空格。
+- 在 markdown 文件中请使用相对路径而不是绝对路径。
+- 请使用列表使描述更加清晰。
+  - 有序列表：通常用来表示列表之间有前后顺序，例如操作步骤。
+  - 无序列表：无序列表中，各个列表之间属于并列关系，没有先后顺序之分，列表前后需要用空行包围。对于有多项参数或者需要描述的，请使用无序列表。
+- 链接
+  - 链接文本需要有意义。例如“请参考[ApacheAPISIX 官网](https://apisix.apache.org/)”，而不是 “请参考[这里](https://apisix.apache.org/)”
+  - 链接不能裸露。例如：“请参考https://apisix.apache.org”。
+  - 内链请使用相对路径。
+
+### 目录结构
+
+文档的目录如下所示。如果要创建新文档，请选择文档写作时所用语言的 `latest` 文件夹中创建一个新文件。
+
+```text
+/docs
+├── assets
+│   ├── images
+│   │   ├── xxxxx.png
+│   └── other
+│       └── xxxxx.xxx
+├── en
+│   └── latest
+│       ├── doc1.md
+│       └── folder
+│           └── doc2.md
+│               └── folder2
+│                   └── doc3.md
+│
+└── zh
+    └── latest
+        └── ...
+```
+
+### 配置文件
+
+配置文件位于 `/docs/<locale>/latest/config.json` 中，其中 locale 表示区域设置代码（语言）。有关详细信息，请参考[本地语言](https://www.science.co.il/language/Locale-codes.php)。请注意，语言环境全部都是小写。
+
+您可以从 [Docusaurus 文档](https://v2.docusaurus.io/docs/next/sidebar)中了解有关侧边栏的更多信息。
+
+```json
+{
+  "version": 2.3,
+  "sidebar": [
+    // The left sidebar of the APISIX website
+    {
+      "type": "doc",
+      "id": "doc2" // id is the filename of the md file
+    },
+    {
+      "type": "category", // category is a collapsed column, nestable
+      "label": "folder",
+      "items": [
+        {
+          "type": "doc",
+          "id": "folder/doc2"
+        },
+        {
+          "type": "category",
+          "label": "folder2",
+          "items": [
+            "folder2/doc3"
+          ]
+        }
+      ]
+    },
+    {
+      "type": "link",
+      "label": "CHANGELOG",
+      "href": "https://github.com/apache/apisix/blob/master/CHANGELOG"
+    }
+  ]
+}
+```
+
+## 图片和嵌入内容
+
+- 请使用高质量的图片，使所呈现的信息对用户清晰可见。

Review Comment:
   ```suggestion
   - 支持的图片格式包括：~~~~~
   - 请使用高质量的图片，使所呈现的信息对用户清晰可见。
   ```



##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者，贡献者应遵循此文档以确保文档一致性。
+
+要了解关于贡献的更多信息，请参考 [Contributor Guide](../docs/general/contributor-guide.md)。
+
+## 语气、内容和受众
+
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”。
+- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
+- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话。例如：打满。
+- 不使用侮辱性词汇。例如：“小白”，可更换为“初学者”。
+- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为 Data Plane（数据面）和 Control Plane（控制面）。
+
+## 语言
+
+- 写作时请尽量使用第二人称，如果不适用第二人称可换成其他人称。
+- 写作时使用主动语态。
+- 句子要求
+  - 避免使用长句。不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，任何情况下都不能接受。
+  - 尽量使用简单句和并列句，避免使用复合句。
+  - 同样一个意思，尽量使用肯定句表达，不使用否定句表达。
+  - 避免使用双重否定句。
+- 请不要在标题、文本、导航或目录中使用`&`代替`和`，`/` 代替 `或`。请参考[一般注意事项](https://developers.google.com/style/accessibility#general-dos-and-donts) 了解更多信息。
+- 对项目特定词汇使用以下拼写：
+  - 在介绍中引用项目和引用项目社区时，使用 Apache APISIX 而不是 APISIX。
+  - 在文档中引用项目时，请使用 APISIX。
+  - APISIX 特定的组件名称，如 Plugin、Route、Service 和 Consumer 等组件名称始终保持首字母大写。
+  - 必要时使用正确的首字母缩略词，例如：
+
+    | ✅              | ❌               |
+    | ---------------- | ---------------- |
+    | URL              | url              |
+    | API              | api              |
+    | APISIX Dashboard | Apisix dashboard |
+    | gRPC             | GRPC/grpc        |
+    | NGINX            | Nginx            |
+
+## 格式、标点和目录
+
+- 标题和副标题应当是有意义的，可以概括文档内容。
+- 必要时请使用 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`）。在解释代码时使用行高亮提高使用者的注意力。
+    - 代码需要是可执行，建议不要在代码前加上系统自带符号。
+    - 多行多条代码请分别用代码块表示。
+    - 长代码需要进行格式化处理，让用户直观的看到命令全文。
+  - 使用[admonitions](https://docusaurus.io/docs/next/markdown-features/admonitions) 突出显示重要信息。按照以下建议使用它们：
+    - Tip：为用户提供基于其他内容的额外提示。一般可以忽略。
+    - Note：想要突出的一般信息，该信息需要用户关注的。
+    - Important：用户需要关注的一般信息，该信息可能需要用户特别注意。
+    - Warning：用户需要特别关注的信息，该操作可能会导致配置或者数据丢失。
+    - Danger：用户应该非常小心该提示中提到的内容，仅在最严重的情况下使用，该操作会导致配置或者数据丢失。
+- 请使用表格描述恰当的内容。请参考[常见问题](/docs/apisix/FAQ#what-is-the-difference-between-plugin-metadata-and-plugin-configs-in-apache-apisix)。

Review Comment:
   This goes to an irrelevant page, please update the link, if no link is suitable, I'd suggest deleting the second part.
   ```suggestion
   - 请使用表格描述恰当的内容。
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-website] SylviaBABY commented on a diff in pull request #1056: docs: update the Chinese Documentation style guide

Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #1056:
URL: https://github.com/apache/apisix-website/pull/1056#discussion_r858165561


##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者，贡献者应遵循此文档以确保文档一致性。
+
+要了解关于贡献的更多信息，请参考 [Contributor Guide](../docs/general/contributor-guide.md)。
+
+## 语气、内容和受众
+
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”。
+- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
+- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话。例如：打满。
+- 不使用侮辱性词汇。例如：“小白”，可更换为“初学者”。
+- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为 Data Plane（数据面）和 Control Plane（控制面）。
+
+## 语言
+
+- 写作时请尽量使用第二人称，如果不适用第二人称可换成其他人称。
+- 写作时使用主动语态。
+- 句子要求
+  - 避免使用长句。不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，任何情况下都不能接受。
+  - 尽量使用简单句和并列句，避免使用复合句。
+  - 同样一个意思，尽量使用肯定句表达，不使用否定句表达。
+  - 避免使用双重否定句。
+- 请不要在标题、文本、导航或目录中使用`&`代替`和`，`/` 代替 `或`。请参考[一般注意事项](https://developers.google.com/style/accessibility#general-dos-and-donts) 了解更多信息。
+- 对项目特定词汇使用以下拼写：
+  - 在介绍中引用项目和引用项目社区时，使用 Apache APISIX 而不是 APISIX。
+  - 在文档中引用项目时，请使用 APISIX。
+  - APISIX 特定的组件名称，如 Plugin、Route、Service 和 Consumer 等组件名称始终保持首字母大写。
+  - 必要时使用正确的首字母缩略词，例如：
+
+    | ✅              | ❌               |
+    | ---------------- | ---------------- |
+    | URL              | url              |
+    | API              | api              |
+    | APISIX Dashboard | Apisix dashboard |
+    | gRPC             | GRPC/grpc        |
+    | NGINX            | Nginx            |
+
+## 格式、标点和目录
+
+- 标题和副标题应当是有意义的，可以概括文档内容。
+- 必要时请使用 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`）。在解释代码时使用行高亮提高使用者的注意力。
+    - 代码需要是可执行，建议不要在代码前加上系统自带符号。
+    - 多行多条代码请分别用代码块表示。
+    - 长代码需要进行格式化处理，让用户直观的看到命令全文。
+  - 使用[admonitions](https://docusaurus.io/docs/next/markdown-features/admonitions) 突出显示重要信息。按照以下建议使用它们：
+    - Tip：为用户提供基于其他内容的额外提示。一般可以忽略。
+    - Note：想要突出的一般信息，该信息需要用户关注的。
+    - Important：用户需要关注的一般信息，该信息可能需要用户特别注意。
+    - Warning：用户需要特别关注的信息，该操作可能会导致配置或者数据丢失。
+    - Danger：用户应该非常小心该提示中提到的内容，仅在最严重的情况下使用，该操作会导致配置或者数据丢失。
+- 请使用表格描述恰当的内容。请参考[常见问题](/docs/apisix/FAQ#what-is-the-difference-between-plugin-metadata-and-plugin-configs-in-apache-apisix)。
+  - 表格中如果尽量不包含空列和空行。
+  - 表格中的描述需要简洁。
+- 中文与英文、阿拉伯数字之间需要包含一个空格。英文和阿拉伯数字在标点符号前或者标点符号后，不需要加空格。
+- 在 markdown 文件中请使用相对路径而不是绝对路径。
+- 请使用列表使描述更加清晰。
+  - 有序列表：通常用来表示列表之间有前后顺序，例如操作步骤。
+  - 无序列表：无序列表中，各个列表之间属于并列关系，没有先后顺序之分，列表前后需要用空行包围。对于有多项参数或者需要描述的，请使用无序列表。
+- 链接
+  - 链接文本需要有意义。例如“请参考[ApacheAPISIX 官网](https://apisix.apache.org/)”，而不是 “请参考[这里](https://apisix.apache.org/)”
+  - 链接不能裸露。例如：“请参考https://apisix.apache.org”。
+  - 内链请使用相对路径。
+
+### 目录结构
+
+文档的目录如下所示。如果要创建新文档，请选择文档写作时所用语言的 `latest` 文件夹中创建一个新文件。
+
+```text
+/docs
+├── assets
+│   ├── images
+│   │   ├── xxxxx.png
+│   └── other
+│       └── xxxxx.xxx
+├── en
+│   └── latest
+│       ├── doc1.md
+│       └── folder
+│           └── doc2.md
+│               └── folder2
+│                   └── doc3.md
+│
+└── zh
+    └── latest
+        └── ...
+```
+
+### 配置文件
+
+配置文件位于 `/docs/<locale>/latest/config.json` 中，其中 locale 表示区域设置代码（语言）。有关详细信息，请参考[本地语言](https://www.science.co.il/language/Locale-codes.php)。请注意，语言环境全部都是小写。
+
+您可以从 [Docusaurus 文档](https://v2.docusaurus.io/docs/next/sidebar)中了解有关侧边栏的更多信息。
+
+```json
+{
+  "version": 2.3,
+  "sidebar": [
+    // The left sidebar of the APISIX website
+    {
+      "type": "doc",
+      "id": "doc2" // id is the filename of the md file
+    },
+    {
+      "type": "category", // category is a collapsed column, nestable
+      "label": "folder",
+      "items": [
+        {
+          "type": "doc",
+          "id": "folder/doc2"
+        },
+        {
+          "type": "category",
+          "label": "folder2",
+          "items": [
+            "folder2/doc3"
+          ]
+        }
+      ]
+    },
+    {
+      "type": "link",
+      "label": "CHANGELOG",
+      "href": "https://github.com/apache/apisix/blob/master/CHANGELOG"
+    }
+  ]
+}
+```
+
+## 图片和嵌入内容
+
+- 请使用高质量的图片，使所呈现的信息对用户清晰可见。
+- 图片需要当前上传到私有 CDN，以确保更小的存储库大小和快速加载。请联系项目团队以上传/更改图片。

Review Comment:
   ```suggestion
   - 目前官网文档中所需图片需要上传到私有 CDN，以确保更小的存储库大小和快速加载。如需在文档中添加图片，请联系项目团队以上传/更改图片。
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-website] SylviaBABY commented on a diff in pull request #1056: docs: update the Chinese Documentation style guide

Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #1056:
URL: https://github.com/apache/apisix-website/pull/1056#discussion_r858165172


##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,147 @@
+---
+id: documentation-style-guide
+title: 中文文档写作指南
+keywords:
+  - API gateway
+  - APISIX
+  - Apache APISIX
+  - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+本文档是 Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文文档的贡献者，贡献者应遵循此文档以确保文档一致性。
+
+要了解关于贡献的更多信息，请参考 [Contributor Guide](../docs/general/contributor-guide.md)。
+
+## 语气、内容和受众
+
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”。
+- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
+- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话。例如：打满。
+- 不使用侮辱性词汇。例如：“小白”，可更换为“初学者”。
+- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为 Data Plane（数据面）和 Control Plane（控制面）。
+
+## 语言
+
+- 写作时请尽量使用第二人称，如果不适用第二人称可换成其他人称。
+- 写作时使用主动语态。
+- 句子要求
+  - 避免使用长句。不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，任何情况下都不能接受。
+  - 尽量使用简单句和并列句，避免使用复合句。
+  - 同样一个意思，尽量使用肯定句表达，不使用否定句表达。
+  - 避免使用双重否定句。
+- 请不要在标题、文本、导航或目录中使用`&`代替`和`，`/` 代替 `或`。请参考[一般注意事项](https://developers.google.com/style/accessibility#general-dos-and-donts) 了解更多信息。
+- 对项目特定词汇使用以下拼写：
+  - 在介绍中引用项目和引用项目社区时，使用 Apache APISIX 而不是 APISIX。
+  - 在文档中引用项目时，请使用 APISIX。
+  - APISIX 特定的组件名称，如 Plugin、Route、Service 和 Consumer 等组件名称始终保持首字母大写。
+  - 必要时使用正确的首字母缩略词，例如：
+
+    | ✅              | ❌               |
+    | ---------------- | ---------------- |
+    | URL              | url              |
+    | API              | api              |
+    | APISIX Dashboard | Apisix dashboard |
+    | gRPC             | GRPC/grpc        |
+    | NGINX            | Nginx            |
+
+## 格式、标点和目录
+
+- 标题和副标题应当是有意义的，可以概括文档内容。
+- 必要时请使用 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`）。在解释代码时使用行高亮提高使用者的注意力。
+    - 代码需要是可执行，建议不要在代码前加上系统自带符号。
+    - 多行多条代码请分别用代码块表示。
+    - 长代码需要进行格式化处理，让用户直观的看到命令全文。
+  - 使用[admonitions](https://docusaurus.io/docs/next/markdown-features/admonitions) 突出显示重要信息。按照以下建议使用它们：
+    - Tip：为用户提供基于其他内容的额外提示。一般可以忽略。
+    - Note：想要突出的一般信息，该信息需要用户关注的。
+    - Important：用户需要关注的一般信息，该信息可能需要用户特别注意。
+    - Warning：用户需要特别关注的信息，该操作可能会导致配置或者数据丢失。
+    - Danger：用户应该非常小心该提示中提到的内容，仅在最严重的情况下使用，该操作会导致配置或者数据丢失。
+- 请使用表格描述恰当的内容。请参考[常见问题](/docs/apisix/FAQ#what-is-the-difference-between-plugin-metadata-and-plugin-configs-in-apache-apisix)。
+  - 表格中如果尽量不包含空列和空行。
+  - 表格中的描述需要简洁。
+- 中文与英文、阿拉伯数字之间需要包含一个空格。英文和阿拉伯数字在标点符号前或者标点符号后，不需要加空格。
+- 在 markdown 文件中请使用相对路径而不是绝对路径。
+- 请使用列表使描述更加清晰。
+  - 有序列表：通常用来表示列表之间有前后顺序，例如操作步骤。
+  - 无序列表：无序列表中，各个列表之间属于并列关系，没有先后顺序之分，列表前后需要用空行包围。对于有多项参数或者需要描述的，请使用无序列表。
+- 链接
+  - 链接文本需要有意义。例如“请参考[ApacheAPISIX 官网](https://apisix.apache.org/)”，而不是 “请参考[这里](https://apisix.apache.org/)”
+  - 链接不能裸露。例如：“请参考https://apisix.apache.org”。
+  - 内链请使用相对路径。
+
+### 目录结构
+
+文档的目录如下所示。如果要创建新文档，请选择文档写作时所用语言的 `latest` 文件夹中创建一个新文件。
+
+```text
+/docs
+├── assets
+│   ├── images
+│   │   ├── xxxxx.png
+│   └── other
+│       └── xxxxx.xxx
+├── en
+│   └── latest
+│       ├── doc1.md
+│       └── folder
+│           └── doc2.md
+│               └── folder2
+│                   └── doc3.md
+│
+└── zh
+    └── latest
+        └── ...
+```
+
+### 配置文件
+
+配置文件位于 `/docs/<locale>/latest/config.json` 中，其中 locale 表示区域设置代码（语言）。有关详细信息，请参考[本地语言](https://www.science.co.il/language/Locale-codes.php)。请注意，语言环境全部都是小写。
+
+您可以从 [Docusaurus 文档](https://v2.docusaurus.io/docs/next/sidebar)中了解有关侧边栏的更多信息。
+
+```json
+{
+  "version": 2.3,
+  "sidebar": [
+    // The left sidebar of the APISIX website
+    {
+      "type": "doc",
+      "id": "doc2" // id is the filename of the md file
+    },
+    {
+      "type": "category", // category is a collapsed column, nestable
+      "label": "folder",
+      "items": [
+        {
+          "type": "doc",
+          "id": "folder/doc2"
+        },
+        {
+          "type": "category",
+          "label": "folder2",
+          "items": [
+            "folder2/doc3"
+          ]
+        }
+      ]
+    },
+    {
+      "type": "link",
+      "label": "CHANGELOG",
+      "href": "https://github.com/apache/apisix/blob/master/CHANGELOG"
+    }
+  ]
+}
+```
+
+## 图片和嵌入内容
+
+- 请使用高质量的图片，使所呈现的信息对用户清晰可见。

Review Comment:
   ```suggestion
   - 请使用高分辨率图片，使所呈现的信息对用户清晰可见。
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-website] netlify[bot] commented on pull request #1056: docs: update the Chinese Documentation style guide

Posted by GitBox <gi...@apache.org>.
netlify[bot] commented on PR #1056:
URL: https://github.com/apache/apisix-website/pull/1056#issuecomment-1108733280

   ### <span aria-hidden="true">👷</span> Deploy Preview for *apache-apisix* processing.
   
   
   |  Name | Link |
   |---------------------------------|------------------------|
   |<span aria-hidden="true">🔨</span> Latest commit | acaee74dff3b26b649f763a727cc5795cd61b0e5 |
   |<span aria-hidden="true">🔍</span> Latest deploy log | https://app.netlify.com/sites/apache-apisix/deploys/6266c01179cb6c0008ea02e4 |


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-website] juzhiyuan commented on a diff in pull request #1056: docs: update the Chinese Documentation style guide

Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on code in PR #1056:
URL: https://github.com/apache/apisix-website/pull/1056#discussion_r858364046


##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,169 @@
+---
+id: documentation-style-guide

Review Comment:
   Hi, @kwanhur, would you please have a review on this guide?



##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -0,0 +1,169 @@
+---
+id: documentation-style-guide

Review Comment:
   Hi, @kwanhur, would you please have a review of this guide?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-website] SylviaBABY merged pull request #1056: docs: update the Chinese Documentation style guide

Posted by GitBox <gi...@apache.org>.
SylviaBABY merged PR #1056:
URL: https://github.com/apache/apisix-website/pull/1056


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix-website] SylviaBABY commented on pull request #1056: docs: update the Chinese Documentation style guide

Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on PR #1056:
URL: https://github.com/apache/apisix-website/pull/1056#issuecomment-1109223165

   I think in this guide, we also need to add Tech Doc reference details, like this(you can edit based on the below part):
   
   ## 添加主库技术文档
   
   如需在本网站【文档-Apache APISIX】下进行技术文档的添加（主要是关于 APISIX 插件的使用文档），可参考以下内容架构：
   - 插件描述（应用该插件可以做什么，为什么开发了此插件等背景信息）
   - 使用或配置该插件时的一些配置释义
   - 如何使用该插件（启用或者前期部署等；如何关闭；如果有特殊情况，该如何使用等）
   - 使用该插件注意事项（可选）
   - 插件后续计划（可选）
   
   如需具体文章参考，可查看xxxxxx


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org