ninehills/tech-doc-style-chinese

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

<!-- 作者：Fenng（GitHub：@Fenng） -->

在以下任务中使用这份 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. 行动按钮文案

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

示例：

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

避免：

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

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

常见内容类型模板

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

入口页或总览页

首段通常回答三件事：

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

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

介绍页

第一段通常说明：

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

解决方案页

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

可参考的顺序：

1. 适用场景
2. 典型问题
3. 推荐方案
4. 推荐调用顺序
5. 实施建议
6. 能力边界

接口说明页

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

常见误译词表：

• Success
  • 不默认写成 成功
  • 按语义选择：已完成、已处理、请求已受理
• Invalid
  • 不翻译成 非法
  • 按语义选择：无效、格式无效、有误、校验未通过
• Available
  • 不机械翻译成 可用
  • 按语义选择：已开通、可获取、可访问、可使用
• Unsupported
  • 优先翻译为：暂不支持、不支持该类型、当前不支持
• Pending
  • 优先翻译为：待处理、处理中、待确认
• Expired
  • 优先翻译为：已过期
• Missing
  • 优先翻译为：缺少、未提供
• Denied
  • 优先翻译为：被拒绝、不予通过
• Forbidden
  • 不直接翻译成 禁止
  • 按语义选择：无权限访问、当前不允许访问
• Not Found
  • 优先翻译为：未找到对应内容、未找到对应数据
• Accepted
  • 不机械翻译成 已接受
  • 按语义选择：已受理、已接收，等待处理
• Completed
  • 优先翻译为：已完成
• Failed
  • 优先翻译为：失败
  • 如上下文更偏流程处理，可用：处理失败
• Conflict
  • 不机械翻译成 冲突
  • 按语义选择：状态冲突、资源状态不一致、请求与当前状态冲突
• Unauthorized
  • 不翻译成 未授权
  • 优先翻译为：未登录、认证未通过、缺少认证信息
• Bad Request
  • 不机械翻译成 错误请求
  • 优先翻译为：请求参数有误、请求格式有误
• Timeout
  • 优先翻译为：超时
  • 如需更完整，可写为：请求超时、处理超时

常见问题与排查页

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

排版与结构规则

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

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

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

界面文案规则

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

移动端可读性规则

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

编辑流程

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

中文易错表达清单

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

• 出生于技术团队 -> 出身于技术团队（出生 仅用于生理出生）
• 阀值 -> 阈值
• 请先登陆系统 -> 请先登录系统（登陆 多用于登岸）
• 截止 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

改写前：

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

改写后：

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