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: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
