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