/technical-writing

name: technical-writing
description: Use when drafting or revising internal technical design docs, review notes, architecture writeups, or sharing posts in Chinese, especially when the tone should stay evidence-backed, calm, and suitable for peers or leaders rather than marketing or literary writing.

Internal Technical Writing

Overview

Use this skill when the writing target is an internal技术方案、评审稿、架构说明、分享文稿，重点在于把背景、猜想、证据、抽象、实现影响面讲清楚。

这类写作更接近技术汇报，不是宣传稿，也不该写成散文。语气要平稳，判断要有来路，段落要能顺着问题往下读。

When to Use

• 在写内部技术方案、设计说明、评审文档、分享稿
• 在改一篇已经有内容、但文风过满、结论过快、证据不足的技术文章
• 在解释代码、模块边界、架构演进、可观测性、评测方法
• 在把聊天记录、讨论结论整理成可传播的技术文档

**When not to use**

• UI 文案、按钮文案、产品营销稿
• 面向外部用户的帮助文档
• 纯粹的 API reference 或机械说明书

Core Stance

先接住读者，再往下解释。

常见写法是作者替读者抢先下判断，像 `很清楚`、`说明了`、`显然`、`真正`。这里更适合换成三步：

1. 我们观察到了什么 2. 基于这些观察，可以归纳出什么 3. 这些归纳暂时更适合落在哪类实现或组织方式里

如果要给出更强的判断，至少满足下面任一条件：

• 前文已经提出了对应的猜想，这一段是在 callback
• 同一段上下文里已经有交叉验证的 evidence
• 已经引用了具体模块、代码、issue、trace、指标或实验结果

这些 bad case 往往有同一种共性：

• 句子承担的是“主持文章”的功能，不是“推进论证”的功能
• 句子在表达作者感受，不是在交代条件、对象、约束或判断
• 句子把英文抽象写作习惯直接投到了中文里
• 句子删掉以后，不影响事实，不影响论证，也不影响结构

遇到这类句子，默认处理方式不是“换个更文雅的说法”，而是：

1. 先判断这句是否真的提供信息 2. 如果不提供信息，直接删除 3. 如果提供信息，就把信息改写成条件、对象、关系、结果

Preferred Structure

写长文时，优先用这条主线：

`背景 -> 拆解现状 -> 提出猜想 -> 分节解答 -> 回指前文 -> 影响面 -> 可观测性 / eval -> 收束`

如果文章围绕一个系统展开，可以把每一节都写成“在回答前面哪个问题”。这样读者会知道当前段落在解决什么，而不是只看到一串观点。

更具体一点，常见结构会是：

• 先交代背景和目标
• 拆现状，尤其是已有系统的优势、局限、宏观规律
• 把猜想或设计问题提出来
• 逐节解释每一层能力怎样补上
• 回到代码、模块、数据流、观测面和评测面

如果某一节表面上在讲模块，实际目的是在替另一个概念安家，可以优先用这种结构：

1. 先用一个很短的 quote 收住上下文 2. quote 里优先放 `mindmap` 或极简结构图 3. 再给一个生命周期或时序图 4. 最后才进入正文，解释这个概念为什么放在这里、怎样和现有模块对上

如果要给 leader 或评审一个放在最开头的 TL;DR，优先用三段结构：

1. 先讲启发来源或背景变化 2. 再讲当前系统已经具备哪些输入、还缺哪一层结构 3. 最后讲新模块设计和架构决策

这个 TL;DR 只保留三类信息：

• 原因
• 猜想
• 决策

不要在 TL;DR 里复述整篇目录，也不要解释作者接下来会怎么写。

Language Rules

中文语气以自然、平实、技术同伴之间的说明为主。

• 中文引用统一用 `「」`
• 少用修辞和比喻，尤其是面对前线开发和内部评审
• 少用居高临下的口吻，避免说教感
• 少写成议论文式对抗句，优先顺着读者的理解路径展开
• 专有概念按正式名字书写，大小写保持稳定，例如项目里的 `Collector`、`Scheduler`、`Alert` 这类专名，全文统一一种写法
• 指标、能力、链路这些名词先钉住，再配动词和形容词；优先复用已经确定的词系，例如 `流通性`、`筛选`、`聚合`、`命中`，不要临时拼接近义词
• 不要写口语化的过场句，例如 `聊到这里`、`继续往下看`、`这条方向很值得继续推开`、`先把这件事单独拿出来说`、`最后可以用一句话收住`；如果一句话只是在主持文章，不承载信息，就直接删掉
• 少用空评价词，例如 `很现实`、`很重`、`很轻`、`很顺`；改成具体约束、具体风险、具体影响

下面这类句型要主动收一层：

• `不是……而是……`
• `不在……而在……`
• `为什么？原因其实很直接`
• `这条路径已经很清楚了`
• `说明了一件事`
• `自然会`
• `真正`

更稳妥的写法通常是：

• `也许你会先想到……`
• `把视线收回到今天的代码里，会先看到几组比较稳定的规律`
• `顺着这些模块往回看，可以归纳出……`
• `前面提到的猜想，在这里开始有了一个更具体的回答`
• `先把判断放轻一些，后面再结合代码或指标继续说明`

遇到段落里的关键问题句，可以适度用 `**...**` 强调，但只留给真正的主问题，不要把普通判断句全部加粗。

Buzzword Blocklist

下面这些词在中文技术文档里几乎都是「让句子看起来有信息，但读完不知道发生了什么」。看到先停一下，能换成具体动作 / 对象 / 约束就换掉。

原则：不是逐词替换，而是逐句重写。原句里如果只有黑话词承载信息，整句通常没信息。删掉看论证少不少东西，少了再补具体的，没少就让它消失。

抽象抢戏词

• `生态` / `生态位` / `产品生态` → 列出具体依赖关系、用户类型或集成方
• `赋能` / `赋能用户` → `让用户能 X` / `把 X 能力开放给 Y`
• `闭环` / `形成闭环` → `X 之后 Y 也接进去了` / `现在能从 A 走到 B 再回到 A`
• `抓手` / `核心抓手` → `我们能改的那一个变量是 X`
• `心智` / `用户心智` / `心智模型` → `用户在第一次看到 X 时会怎么想 / 怎么操作`
• `链路打通` / `打通` → `A 现在能调用 B` / `A 写入的数据 B 也能读到`
• `沉淀` / `沉淀经验` / `沉淀方法论` → `记录到 docs/X` / `整理成 skill / runbook`
• `落地` / `落地能力` / `落地场景` → `在 A 模块实现` / `在 B 业务用上`
• `心力` / `认知负担` → `需要记住 X 个步骤` / `上手要先理解 Y`
• `收口` / `统一收口` → `所有 X 都走 Y 一个入口`
• `加持` / `AI 加持` → `加了 X 之后能 Y` / `在 X 步用了 LLM`
• `底座` / `底层逻辑` → `基础设施层是 X` / `这件事成立的前提是 Y`

评价腔 / 主持腔

• `很值得` / `非常值得` → 给具体理由：值得在哪个维度上
• `极致` / `极致体验` → 改成具体指标：延迟降到多少、步骤减到几步
• `丝滑` / `顺畅` → 改成具体约束：哪步原本卡，现在跳过了
• `深度集成` / `深度对接` → 改成集成点的具体范围
• `一站式` → `在 A 入口能完成 B / C / D`
• `颠覆` / `重塑` → 默认不用；真要用得有 before / after 对比

Evidence-First Writing

写代码和架构时，避免直接把实现细节翻译成抽象结论。

推荐顺序：

`代码 / issue / trace / metric -> 宏观规律 -> 抽象归纳 -> 设计判断`

例如，不要直接写：

> 当前代码里，这条路径已经很清楚了。

更适合写成：

> 把视线收回到今天的代码里，会看到几组比较稳定的宏观规律。顺着这些模块往回看，可以先归纳出一个较稳定的结构。前面提到的几层能力，也因此开始有了几种更适合继续承接的实现位置。

Reader-Aware Explanations

很多技术分歧来自“作者默认读者已经接受了自己的前提”。这里更适合先猜测读者可能会怎么想，再把误会拆开。

常用句法：

• `也许你会先想到定时巡检，像是……`
• `顺着这个方向想下去，会发现我们更关心的是……`
• `这样理解，会更贴近这次设计的边界`

适合接一个 quote：

> 一条巡检任务如何按预定周期扫描每个指标

然后再转入你真正要讨论的问题：

> 持续涌入的原始日志，怎样在不拖慢写入链路的情况下，被判定成一条值得通知的告警

Few-Shot Fixes

下面这些例子比抽象规则更重要。写作时如果遇到类似句式，优先按这个方式改。

1. 不要把英文里的 `real / realize / reality` 直接翻进中文

原句：

> 一旦把告警规则接到多个采集端上，粒度问题会马上变得很现实。

问题：

• `现实` 在这里不是合适的表语
• 主语是 `粒度问题`，谓语是 `变得`，搭配不成立
• 句子像是在表达感受，不是在说明约束

改写：

> 可以预见的是，告警规则接入多个采集端之后，规则粒度的控制会很重要。

为什么这样改：

• 先写条件：`接入多个采集端之后`
• 再写对象：`规则粒度的控制`
• 最后写判断：`会很重要`

2. 不要用空评价词替代约束

原句：

> 这样的组合很顺。

问题：

• `很顺` 只有情绪，没有信息
• 读者不知道顺在成本、链路、延迟还是模块边界

改写：

> 这种组合更接近实际分工。

或者：

> 这种组合能把日志写入链路和告警判定链路拆开。

为什么这样改：

• 直接说分工关系
• 或者直接说结构变化
• 不用作者主观感受替代技术判断

3. 不要用对立句法硬造强调

原句：

> 它值得认真看的地方，不在宣传语，而在它把一组采集与告警机制组织得很完整。

问题：

• `不在……而在……` 容易写出说教感
• 读者还没进入正文，就先被作者带去站队

改写：

> 更值得认真拆开的，是它把一组采集与告警机制组织得比较完整。

为什么这样改：

• 少掉对立结构
• 句子仍然保留重音
• 读者更容易直接进入后文

4. 不要用过场句替代内容

原句：

> 聊到这里，告警去重相关的模型也该放进来一起看了。

问题：

• 这是主持人口吻，不是技术文档
• 删掉这句，论证不会损失任何信息

改写：

> 告警去重相关的模型也需要放进来一起讨论。

为什么这样改：

• 直接进入主题
• 不拿过场句占正文位置

同类句子也直接删掉，不做“温和改写”：

原句：

> 先把「压缩」这件事单独拿出来说。

问题：

• 这是主持句，不提供任何新信息
• 删掉之后，后文论证不受影响

处理：

> 直接删除，让下一句作为段落开头

5. 不要把“主持文章”的句子写进正文

原句：

> 这张图想说明的事情很简单。

问题：

• 这是主持句，不提供图外的新信息
• 读者真正需要的是图后的结论，不是作者先出面做导语

处理：

> 直接删除，下一句直接解释图里的结构关系

原句：

> 接下来进入这一节真正关心的问题：

问题：

• 这句话只是在带节奏，没有补充任何事实
• 如果下一句本身已经是问题句，这一句就没有存在价值

处理：

> 直接删除，或者把下一句改成完整的问题句

原句：

> 最后可以用一句更轻一点的话结束：

问题：

• 这句话只是在管理作者自己的写作动作
• 正文里不需要暴露作者“现在准备收尾”

处理：

> 直接删除，让引文或结论直接出现

6. 论证有顺序，就直接写成 1. 2. 3. 4.

原句：

> 第一，采集端很多，但日志最终还是会被收束到告警引擎。 > 第二，采集层已经承担了日志归一化…… > 第三，告警引擎自己已经天然拥有一组规则边界…… > 第四，外围模块已经把不少有价值的事件散落出来了……

问题：

• 如果只是散写四段，读者不容易看出这是一组并列论据
• 论据顺序和论证强度不够醒目

改写：

1. 采集端很多，但日志最终还是会被收束到告警引擎。 2. 采集层已经承担了日志归一化、字段提取、标签注入、来源标注。 3. 告警引擎自己已经拥有一组稳定的规则边界。 4. 外围模块已经给出了足够多的事件与状态。

为什么这样改：

• 论证顺序被显式标出来
• 每一点都能单独成立
• 后文更容易 callback

7. 指标名和动作词要属于同一套语义系统

原句：

> 第一组命题靠近转化率。不同 source 类型进入系统之后，有多少被 dedupe 掉，有多少在 cooldown 里停住，有多少被 policy 接住，最后又有多少真的升级成一条告警。

问题：

• `转化率`、`dedupe 掉`、`停住`、`接住`、`升级` 混了多套词
• 指标名和动作词不在一个语义系统里

改写：

> 1. 计算流通性。 > 不同 source 类型进入系统之后： > - 有多少被 dedupe 筛选 > - 有多少进入 cooldown 聚合 > - 有多少被 policy 命中 > - 最后又有多少升级成一条告警

为什么这样改：

• 先钉住指标名：`流通性`
• 再统一动作词：`筛选 / 聚合 / 命中 /