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/05/20 09:25:24 UTC
[GitHub] [apisix-website] hf400159 opened a new pull request, #1105: docs: update doc style guide
hf400159 opened a new pull request, #1105:
URL: https://github.com/apache/apisix-website/pull/1105
Fixes: #[Add issue number here]
Changes:
<!-- Add here what changes were made in this pull request and if possible provide links showcasing the changes. -->
Screenshots of the change:
<!-- Add screenshots depicting the changes. -->
--
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 #1105: docs: update doc style guide
Posted by GitBox <gi...@apache.org>.
netlify[bot] commented on PR #1105:
URL: https://github.com/apache/apisix-website/pull/1105#issuecomment-1132681200
### <span aria-hidden="true">👷</span> Deploy request for *apache-apisix* pending review.
[Visit the deploys page to approve it](https://app.netlify.com/sites/apache-apisix/deploys)
| Name | Link |
|---------------------------------|------------------------|
|<span aria-hidden="true">🔨</span> Latest commit | 71f0310699a1378b457af035c73fcb9e38448b6b |
--
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 #1105: docs: update doc style guide
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #1105:
URL: https://github.com/apache/apisix-website/pull/1105#discussion_r879408201
##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -15,26 +15,29 @@ description: Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文
## 语气、内容和受众
-- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”或着直接用“用户需要”等统称。。
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”或着直接用“用户需要”等统称。
- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话或互联网词汇。例如：打满。
- 不使用具有歧义的词汇。例如：“小白”，可更换为“初学者”。
-- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为 数据面（Data Plane，简称 DP）和控制面（Control Plane，简称 CP）。
+- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为数据面（Data Plane，简称 DP）和控制面（Control Plane，简称 CP）。
## 语言
- 写作时请尽量使用第二人称，如果不适用第二人称可统一替换为统称——用户或使用者。
-- 写作时使用主动语态。
+- 写作时使用主动语态，不要使用被动语态。
+- 如果是英译中的文档，需要符合中文阅读习惯，并确保句子通顺，无语病。
+- 涉及到运算符的句子，运算符连接的部分需要使用代码块表示。例如：我们都知道 `2+3=5`。
- 句子要求
- 避免使用长句。不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，任何情况下都不能接受。
- 尽量使用简单句和并列句，避免使用复合句。
- 同样一个意思，尽量使用肯定句表达，不使用否定句表达。
- 避免使用双重否定句。
- - 在标题、正文、导航或目录中，请不要使用 `&` 代替`和`，`/` 代替`或`。请参考[一般注意事项](https://developers.google.com/style/accessibility#general-dos-and-donts) 了解更多信息。
+ - 在标题、正文、导航或目录中，请不要使用`&`代替`和`，`/`代替`或`。请参考[一般注意事项](https://developers.google.com/style/accessibility#general-dos-and-donts)了解更多信息。
+ - 句子中需要正确使用`的`、`地`、`得`。
- 对项目特定词汇使用以下拼写：
- 在介绍中引用项目和引用项目社区时，使用 Apache APISIX 而不是 APISIX。
- 在文档中引用项目时，请使用 APISIX。
- - APISIX 特定的组件名称，如 Plugin、Route、Service 和 Consumer 等组件名称始终保持首字母大写。
+ - APISIX 特定的组件名称，如 Plugin、Route、Service 和 Consumer 等组件名称始终保持首字母大写。如果是表示概念则使用英文书写，如果表示一个实体（例如：创建一个路由。），则使用中文名称。
Review Comment:
```suggestion
- APISIX 特定的组件名称，如 Plugin、Route、Service 和 Consumer 等组件名称始终保持首字母大写。如果是表示概念则使用英文书写，如果表示一个实体（例如：创建一个路由），则使用中文名称。
```
--
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] github-actions[bot] commented on pull request #1105: docs: update doc style guide
Posted by GitBox <gi...@apache.org>.
github-actions[bot] commented on PR #1105:
URL: https://github.com/apache/apisix-website/pull/1105#issuecomment-1132695719
<!-- NETLIFY DEPLOY COMMENT GENERATED BY ACTIONS_NETLIFY - APP ID SHA256: 4a1e2936f4b00e970c8b5babdfe5b33e6e83e97b6f6d6dda75b1fe8399056321 -->
🚀 Deployed on https://6287613fa0e4bc3783ada4d5--apache-apisix.netlify.app
--
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 merged pull request #1105: docs: update doc style guide
Posted by GitBox <gi...@apache.org>.
juzhiyuan merged PR #1105:
URL: https://github.com/apache/apisix-website/pull/1105
--
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 #1105: docs: update doc style guide
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #1105:
URL: https://github.com/apache/apisix-website/pull/1105#discussion_r879410301
##########
website/i18n/zh/docusaurus-plugin-content-docs/current/documentation-guide.md:
##########
@@ -15,26 +15,29 @@ description: Apache APISIX 中文文档的贡献指南，适用于 APISIX 中文
## 语气、内容和受众
-- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”或着直接用“用户需要”等统称。。
+- 以友好和尊重语气为目标，尽量避免强硬的词汇。例如：“你必须”，“你一定要”。该类词汇可换成：“你需要”或着直接用“用户需要”等统称。
- 确定文档的受众以及文档的目的，为你和你的目标受众找到共同点，然后进行写作。
- 避免口语化描述，不使用冷僻、生造的词汇、不使用行业黑话或互联网词汇。例如：打满。
- 不使用具有歧义的词汇。例如：“小白”，可更换为“初学者”。
-- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为 数据面（Data Plane，简称 DP）和控制面（Control Plane，简称 CP）。
+- 文档中第一次出现英语词汇或者名词缩写时，应当给出全称及中文解释。例如：Apache APISIX 从底层架构来看，分为数据面（Data Plane，简称 DP）和控制面（Control Plane，简称 CP）。
## 语言
- 写作时请尽量使用第二人称，如果不适用第二人称可统一替换为统称——用户或使用者。
-- 写作时使用主动语态。
+- 写作时使用主动语态，不要使用被动语态。
+- 如果是英译中的文档，需要符合中文阅读习惯，并确保句子通顺，无语病。
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