chinese-documentationlisted

# 中文技术文档写作规范 ## 概述 中文技术文档最常见的问题不是内容不够，而是**读起来别扭**——中英文挤在一起没有空格、全角半角混用、一股机翻味。本技能提供一套完整的中文技术文档写作规范，让你的文档**专业、好读、不出戏**。 **核心原则：** 排版服务于阅读体验，规范服务于一致性��内容服务于读者。 **参考标准：** [中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines) ## 中文排版规范 ### 空格 **中英文之间加空格：** ``` # 好 使用 Git 进行版本管理，配合 Jenkins 实现持续集成。 # 坏 使用Git进行版本管理，配合Jenkins实现持续集成。 ``` **中文与数字之间加空格：** ``` # 好 本次更新包含 3 个新功能和 12 个 Bug 修复。 # 坏 本次更新包含3个新功能和12个Bug修复。 ``` **数字与单位之间加空格：** ``` # 好 文件大小不超过 5 MB，响应时间控制在 200 ms 以内。 # 坏 文件大小不超过5MB，响应时间控制在200ms以内。 ``` **例外：度数、百分比等不加空格：** ``` # 好 今天气温 32°C，CPU 使用率 95%。 # 坏 今天气温 32 °C，CPU 使用率 95 %。 ``` **链接前后加空格：** ``` # 好 请参考 [官方文档](https://example.com) 获取更多信息。 # 坏 请参考[官方文档](https://example.com)获取更多信息。 ``` ### 标点符号 **中文语境使用全角标点：** ``` # 好 注意：该接口需要鉴权，请先获取 Token。 # 坏 注意:该接口需要鉴权,请先获取 Token. ``` **全角标点与英文/数字之间不加空格：** ``` # 好 项目使用 MIT 协议，详见 LICENSE 文件。 # 坏 项目使用 MIT 协议 ，详见 LICENSE 文件 。 ``` **括号的使用：** ``` # 中文语境用全角括号 请运行安装命令（详见下方说明）。 # 括号内有英文或数字时用半角括号 该项目基于 Spring Boot (v3.2.0) 开发。 # 纯英文内容用半角括号 See the documentation (README.md) for details. ``` **引号的使用：** ``` # 中文使用直角引号（推荐） 「确定」按钮触发表单提交，「取消」按钮关闭弹窗。 # 也可以使用弯引号（视团队规范而定） "确定"按钮触发表单提交，"取消"按钮关闭弹窗。 # 嵌套引号 他说：「请点击『确定』按钮。」 ``` ### 数字 ``` # 阿拉伯数字（技术文档中统一使用半角数字） 支持最多 100 个并发连接。 # 不要用中文数字写技术参数 # 坏：支持最多一百个并发连接。 # 数字使用半角字符 版本号 v2.1.0，端口号 8080，HTTP 状态码 200。 ``` ## 中英混排最佳实践 ### 术语处理原则 **保留英文的情况：** - 专有名词：React、Kubernetes、Redis、MySQL - 行业通用缩写：API、SDK、CLI、ORM、CI/CD - 命令和代码：`npm install`、`git commit` - 协议和标准：HTT