tech-doc-style-chinese

Name: tech-doc-style-chinese
Rating: 4.3 (331 reviews)
Author: Fenng

在撰写、改写或审阅中文技术文档、文档首页、产品文案、界面文案、Markdown 文档或接口说明时使用。采用克制、准确、可扫读的中文技术写作风格：避免第二人称和宣传腔，统一使用直角引号，在可见正文中处理中文与英文或数字的留白，不改动代码字面量、JSON 键名、URL、API 路径等机器可读内容。如项目存在专属术语、版本展示或信息架构约定，再按需读取 references/Project-Overrides.md。

install

source · Clone the upstream repo

git clone https://github.com/Fenng/Tech-Doc-Style-Chinese

Claude Code · Install into ~/.claude/skills/

git clone --depth=1 https://github.com/Fenng/Tech-Doc-Style-Chinese ~/.claude/skills/fenng-tech-doc-style-chinese-tech-doc-style-chinese

manifest: SKILL.md

source content

中文技术文档与产品文案排版规范

在以下任务中使用这份 Skill：

文档首页、落地页、首屏文案
接口文档、参数说明、常见问题、更新日志
产品能力介绍、解决方案页、能力说明页
界面文案、按钮文案、导航标签、提示信息

不要用这份 Skill 去改写代码字面量、JSON 键名、URL、API 路径、数据库字段名或其他机器可读标识符。

如果项目存在专属术语、版本展示、信息架构或品牌约定，再按需读取

references/Project-Overrides.md

。

目标

准确先于修辞
清晰先于热闹
导航感先于宣传感
可扫读先于堆砌解释
以信息架构和内容组织引导阅读，而不是依赖修辞或口号式表达

语气

使用克制、直接、可执行的中文
以说明、界定、引导为主，不用夸张宣传语
避免「领先」「强大」「重磅」「颠覆」「震惊」「炸裂」「恭喜」等空泛形容
优先陈述「是什么、适用于什么、下一步看哪里」
不用第二人称
避免问候式开场、平台营销话术和口号式抽象表达
避免使用
```
Hello
```
、
```
Hi
```
这类问候式开场

黑话短名单

默认避免以下高危黑话词，除非用户明确要求保留，或该词在当前语境中有严格业务定义：

```
赋能
```
```
抓手
```
```
闭环
```
```
沉淀
```
```
对齐
```
```
对标
```
```
拉通
```
```
打通
```
```
协同
```
```
联动
```
```
洞察
```
```
赛道
```
```
心智
```
```
调性
```
```
战役
```
```
链路
```
```
势能
```
```
兜底
```

以下中危词只有在语义明确时才使用：

```
场景
```
```
生态
```
```
体系
```
```
路径
```
```
触点
```
```
卡点
```
```
布局
```
```
矩阵
```
```
颗粒度
```
```
复盘
```
```
梳理
```
```
输出
```
```
提炼
```

优先替换为更具体的表达：

```
赋能
```
->
```
提供
```
```
抓手
```
->
```
关键措施
```
```
闭环
```
->
```
完整流程
```
```
沉淀
```
->
```
形成
```
/
```
积累
```
```
对齐
```
->
```
统一
```
```
拉通
```
/
```
打通
```
->
```
连接
```
/
```
贯通
```
```
洞察
```
->
```
分析结论
```
```
兜底
```
->
```
保障机制
```

仅在以下情况允许保留黑话原词：

用户明确要求保留原词
正在引用原始材料、访谈、方案原文或外部文档
该词在特定行业语境里有固定含义，替换后会损失准确性
该词是产品名称、功能名称、方法论名称或组织内部正式术语

如果保留黑话原词，优先采用以下处理方式：

首次出现时给出更具体解释
在同一句或下一句说明它实际指什么
避免连续堆叠多个黑话词

强制规则

1. 标点

中文引号统一使用直角引号：
```
「」
```
不使用中文双引号：
```
“”
```
正文中避免连续使用多个感叹号、省略号、宣传口号式断句
避免使用感叹号

2. 称呼与受众

不使用：
```
你
```
、
```
您
```
、
```
同学
```

根据语境替换为：

开发者

、

技术负责人

、

实施人员

、

业务负责人

、

产品经理

如无必要，不直接点名读者，用无主句或说明句即可

3. 中文与英文、数字之间的留白

在可见正文中，中文与可读的半角英文单词、英文缩写、独立数字和版本号之间保留空格，以提高可读性。

推荐写法：

```
获取批量 ID
```
```
HTTP 请求
```
```
版本 2.0
```
```
AI 服务
```
```
与 PM 协作
```
```
读取系统日志
```

以下内容不要机械加空格：

行内代码和代码块
JSON 键名
URL
API 路径
数据库字段名
表头中直接镜像接口字段定义的标签
用户明确指定的拼写或大小写

示例：

```
user_id
```
保持原样
```
/api/example
```
保持原样
```
statusCode
```
保持原样
```
header_name
```
保持原样

说明：

将中西文留白视为最终校对规则，而不是机械替换规则
不直接使用
```
pangu.js
```
批量处理 Markdown 文档
如遇字段名、协议名、路径或术语边界不清的情况，优先保持原样并人工判断

4. 可见术语的大小写归一

仅对可见正文中的自然语言短语做归一：

```
Id
```
/
```
id
```
/
```
ID
```
->
```
ID
```
```
http
```
/
```
Http
```
/
```
HTTP
```
->
```
HTTP
```
```
url
```
/
```
URL
```
/
```
Url
```
->
```
URL
```
```
json
```
/
```
JSON
```
/
```
Json
```
->
```
JSON
```
```
api
```
/
```
Api
```
/
```
API
```
->
```
API
```
```
ai
```
/
```
Ai
```
/
```
AI
```
->
```
AI
```

术语大小写归一扩展清单（高频）

以下清单用于补充高频技术术语，写法统一为

错写 -> 推荐

。仅作用于可见正文，不作用于代码、路径、字段和配置项字面量。

```
java
```
->
```
Java
```
```
javascript
```
->
```
JavaScript
```
```
typescript
```
->
```
TypeScript
```
```
JS
```
/
```
Js
```
->
```
JavaScript
```
```
llm
```
/
```
Llm
```
->
```
LLM
```
```
aigc
```
/
```
Aigc
```
->
```
AIGC
```
```
rag
```
/
```
Rag
```
->
```
RAG
```
```
chatgpt
```
/
```
Chatgpt
```
->
```
ChatGPT
```
```
openai api
```
/
```
OpenAI api
```
->
```
OpenAI API
```
```
embeding
```
->
```
embedding
```
```
finetune
```
/
```
fine tune
```
->
```
fine-tuning
```
（如语义是训练过程，也可直接写
```
微调
```
）
```
python
```
->
```
Python
```
```
golang
```
/
```
go
```
（指语言名） ->
```
Go
```
```
rust
```
->
```
Rust
```
```
kotlin
```
->
```
Kotlin
```
```
swift
```
->
```
Swift
```
```
php
```
->
```
PHP
```
```
ruby
```
->
```
Ruby
```
```
scala
```
->
```
Scala
```
```
dart
```
->
```
Dart
```
```
sql
```
->
```
SQL
```
```
bash
```
->
```
Bash
```
```
powershell
```
->
```
PowerShell
```
```
nodejs
```
/
```
node
```
（指运行时或平台名） ->
```
Node.js
```
```
dotnet
```
->
```
.NET
```
```
reactjs
```
->
```
React
```
```
vuejs
```
->
```
Vue
```
```
nextjs
```
->
```
Next.js
```
```
nuxtjs
```
->
```
Nuxt
```
```
vitejs
```
->
```
Vite
```
```
tailwind
```
->
```
Tailwind CSS
```
```
nginx
```
->
```
Nginx
```
```
redis
```
->
```
Redis
```
```
postgres
```
/
```
postgresql
```
->
```
PostgreSQL
```
```
mysql
```
->
```
MySQL
```
```
mongodb
```
->
```
MongoDB
```
```
elasticsearch
```
->
```
Elasticsearch
```
```
kafka
```
->
```
Kafka
```
```
rabbitmq
```
->
```
RabbitMQ
```
```
github
```
->
```
GitHub
```
```
gitlab
```
->
```
GitLab
```
```
docker
```
->
```
Docker
```
```
k8s
```
（正式文案） ->
```
Kubernetes
```
```
https
```
->
```
HTTPS
```
```
grpc
```
->
```
gRPC
```
```
graphql
```
->
```
GraphQL
```
```
websocket
```
->
```
WebSocket
```
```
yaml
```
->
```
YAML
```
```
xml
```
->
```
XML
```
```
jwt
```
->
```
JWT
```
```
oauth
```
->
```
OAuth 2.0
```
```
H5
```
->
```
HTML5
```
（如语义是移动 Web 页面，优先直接写
```
移动 Web 页面
```
）

适用示例：

```
批量 id
```
->
```
批量 ID
```
```
接口 url
```
->
```
接口 URL
```
```
响应 json
```
->
```
响应 JSON
```
```
启用 rag
```
->
```
启用 RAG
```
```
接入 chatgpt
```
->
```
接入 ChatGPT
```
```
调用 openai api
```
->
```
调用 OpenAI API
```

以下内容不要改写：

机器可读标识符
字段化标签，如
```
user_id
```
直接镜像接口定义的表头
用户明确指定的大小写

5. 行动按钮文案

按钮文案应体现下一步动作，避免与标题重复
优先使用「动作 + 结果」或「动作 + 目标」

示例：

```
从这里开始
```
```
核对调用规则
```
```
初步了解
```

避免：

```
阅读平台介绍
```
```
查看认证规则
```

当标题已经表达同一信息时，不要在行动按钮文案里重复。

常见内容类型模板

以下模板是通用写法参考，不是强制结构。项目如有专属信息架构，优先服从项目覆盖规则。

入口页或总览页

首段通常回答三件事：

覆盖什么
适合谁使用
从哪里开始读

段落保持紧凑，不要叠加口号式表达。

介绍页

第一段通常说明：

这页给谁看
这页解决什么问题
建议接着读哪里

解决方案页

按业务用途组织，而不是按接口清单平铺。

可参考的顺序：

适用场景
典型问题
推荐方案
推荐调用顺序
实施建议
能力边界

接口说明页

请求方法行放进代码块，不要裸露在正文里
参数说明尽量一列一义，不写含混描述
错误码文案要统一口径
不要机械直译常见英文状态词和错误词

常见误译词表：

Success

不默认写成
```
成功
```
按语义选择：
```
已完成
```
、
```
已处理
```
、
```
请求已受理
```

Invalid

不翻译成
```
非法
```
按语义选择：
```
无效
```
、
```
格式无效
```
、
```
有误
```
、
```
校验未通过
```

Available

不机械翻译成
```
可用
```
按语义选择：
```
已开通
```
、
```
可获取
```
、
```
可访问
```
、
```
可使用
```

Unsupported

优先翻译为：

暂不支持

、

不支持该类型

、

当前不支持

```
Pending
```
- 优先翻译为：
```
待处理
```
  、
```
处理中
```
  、
```
待确认
```
```
Expired
```
- 优先翻译为：
```
已过期
```
```
Missing
```
- 优先翻译为：
```
缺少
```
  、
```
未提供
```
```
Denied
```
- 优先翻译为：
```
被拒绝
```
  、
```
不予通过
```

Forbidden

不直接翻译成
```
禁止
```
按语义选择：
```
无权限访问
```
、
```
当前不允许访问
```

Not Found

优先翻译为：

未找到对应内容

、

未找到对应数据

Accepted

不机械翻译成
```
已接受
```
按语义选择：
```
已受理
```
、
```
已接收，等待处理
```

```
Completed
```
- 优先翻译为：
```
已完成
```
```
Failed
```
- 优先翻译为：
```
失败
```
- 如上下文更偏流程处理，可用：
```
处理失败
```

Conflict

不机械翻译成
```
冲突
```

按语义选择：

状态冲突

、

资源状态不一致

、

请求与当前状态冲突

Unauthorized

不翻译成
```
未授权
```

优先翻译为：

未登录

、

认证未通过

、

缺少认证信息

Bad Request

不机械翻译成
```
错误请求
```
优先翻译为：
```
请求参数有误
```
、
```
请求格式有误
```

```
Timeout
```
- 优先翻译为：
```
超时
```
- 如需更完整，可写为：
```
请求超时
```
  、
```
处理超时
```

常见问题与排查页

先给判断路径，再给例外
优先说明「先查什么」，而不是只罗列概念
错误排查文本要偏操作性，不要写成泛泛说明

排版与结构规则

一个段落只承载一个主要信息点
长句可以保留，但避免连续堆叠两个以上长句
列表项要平行，不要有的写定义、有的写宣传、有的写结论
标题要能反映用途，不要只写抽象名词

当同一标题下出现 4 个及以上并列项时：

统一命名结构
统一句式
统一信息密度

界面文案规则

按钮文案短，不解释背景
卡片描述补信息，不重复标题
导航标题偏名词
行动文案偏动作

移动端可读性规则

三列表参数表在移动端不应靠缩字硬挤
常见
```
参数 / 是否必填 / 说明
```
表优先改卡片式行布局
真正宽表再使用横向滚动

编辑流程

先判断内容类型。例如：入口页、介绍页、解决方案页、接口说明页、常见问题、界面文案。
先去重复。如果标题、正文和行动按钮文案在表达同一件事，优先重写行动按钮文案。
应用强制规则。统一标点、称呼、留白和常见误译词。
再收句子。只保留准确阅读和下一步导航所必需的信息。
最后通读。检查语气、术语、留白、标题和扫读节奏。

中文易错表达清单

用于排查词义错位、数量逻辑错误和表达歧义。优先写成「具体、可验证、不歧义」的表达。

出生于技术团队

出身于技术团队

（

出生

仅用于生理出生）

```
阀值
```
->
```
阈值
```

请先登陆系统

请先登录系统

（

登陆

多用于登岸）

截止 4 月 12 日

截至 2026 年 4 月 12 日

（时间范围优先用

截至

，并给完整日期）

布署到生产环境

部署到生产环境

配制服务器参数

配置服务器参数

```
起用该功能
```
->
```
启用该功能
```
```
反回结果
```
->
```
返回结果
```
```
回朔历史版本
```
->
```
回溯历史版本
```
```
标示字段
```
->
```
标识字段
```
（指 ID、标签、标记物时）
```
帐户余额
```
->
```
账户余额
```
（金融语境）
```
帐号登录
```
->
```
账号登录
```
（平台用户语境，建议统一）
```
搜寻日志
```
->
```
搜索日志
```
```
即时通信
```
->
```
实时通信
```
（系统能力描述语境）
```
做为默认配置
```
->
```
作为默认配置
```

系统发布到生产环境

部署到生产环境

发布新版本

（区分

部署

与

发布

）

```
完成授权
```
（语义为身份校验） ->
```
完成认证
```
（认证 = 确认身份，授权 = 授予权限）

缩小了 3 倍

缩小到原来的 1/3

减少了 2/3

增长到 30%

（原来 20%） ->

从 20% 提高到 30%

相对增长 50%

转化率提升了 5%

（20% -> 25%） ->

提升了 5 个百分点

相对提升 25%

```
翻了 1 倍
```
->
```
变为原来的 2 倍
```
```
不超过 100 以上
```
->
```
不超过 100
```

预计大约在 3 点左右

预计 3 点

预计 3 点左右

是否可以 A 或者 B

可以 A 或者 B

是否可以 A

```
尽快处理
```
->
```
30 分钟内处理
```
（将模糊词改为明确时限）

使用提示工程学优化输出

使用提示工程优化输出

```
模型出现幻听
```
->
```
模型出现幻觉
```

最终检查清单

交付前检查：

是否出现
```
你
```
、
```
您
```
、
```
同学
```
是否出现中文双引号
```
“”
```
中文与英文、数字之间是否需要留白
文案是否重复标题
行动按钮文案是否与标题重复
是否存在过强的宣传口吻
文案是否便于扫读

改写示例

示例 1

改写前：

阅读平台介绍

改写后：

从这里开始

示例 2

改写前：

本页适合第一次进入文档中心的业务负责人、产品经理、技术负责人和实施同学。

改写后：

本页适合首次访问文档中心的业务负责人、产品经理、技术负责人和实施人员。

示例 3

改写前：

获取数据批量ID

改写后：

获取数据批量 ID

示例 4

改写前：

集中说明请求头、签名算法、时间戳与错误码，适合发起请求前逐项核对。

改写后：

集中说明通用技术约定，适合发起请求前快速逐项核对。