Tech Writing Expert

---
name: tech-writing-expert
description: "技术表达.Skill。只要用户要把技术写给一个具体的人看、而且读完要对方给个回应，即应触发本技能，无需用户明确指定。无论是技术方案与设计文档怎么写、RFC 与立项材料怎么搭、第一屏该放什么、方案写完了怕评审会上被挑穿想先自审一遍，还是周报月报没东西写、这周全在查一个线上问题、迭代进展怎么同步、述职与晋升答辩材料怎么搭、一年的活讲不出高度、故障复盘报告怎么写、讨论要落成需求文档再拆成任务，或者产品经理老板客服听不懂要说人话、跨团队同一个词两种意思、同一个东西一会儿叫任务一会儿叫作业、这个选型要不要记成 ADR、邮件或 IM 发出去没人理想要个回话、技术分享稿与 PPT 大纲从哪起、PR 描述与对外版本说明和 release notes 怎么写、休假转岗要留一份交接、要写给 AI 或 Agent 看的规则文档、写完想做一次读者测试，都从这里进。本技能先定读者与你要的那个决定再动笔。不做：写接口文档与代码注释，不编数字，也不替人按发送键。"
author: Captain
version: 0.1.3
display_name: "技术文档"
display_name_en: "Tech Communication.Skill"
description_zh: "一个入口覆盖技术人对人的表达，不必等用户报出技能名：方案文档与 RFC、周报月报与述职、晋升答辩、故障复盘、需求 Spec 与任务拆解、分享稿与 PPT 大纲、给非技术同事的解释、要结果的邮件与 IM、PR 描述与版本说明、交接文档。先定读者与你要的决定，再动笔。"
description_en: "One entry point for explaining technology to people, triggered by the writing task rather than by name. Design docs and RFCs, weekly and monthly reports, promotion packets, incident postmortems, specs and ticket breakdowns, talk outlines and slide skeletons, plain-language explanations for non-engineers, emails that get a reply, PR descriptions and release notes, handoff docs. Reader first, decision first."
tags:
  - "技术写作"
  - "技术方案"
  - "周报"
  - "述职"
  - "晋升答辩"
  - "故障复盘"
  - "技术分享"
  - "说人话"
examples_zh:
  - "周报没东西写，这周全在查一个线上问题"
  - "产品经理听不懂我为什么要重构，这封邮件怎么写才有人理"
  - "晋升答辩材料怎么搭，我一年的活讲不出高度"
examples_en:
  - "Nothing to put in my weekly report, I spent the week on one bug"
  - "The PM does not get why we need this refactor, help me write the mail"
  - "Build my promotion packet, a year of work with no story"
metadata:
  { "openclaw": { "requires": { "bins": ["git", "python3"] }, "os": ["darwin", "linux", "windows"], "emoji": "🖋" } }
---

# 技术表达

定位一句话：**代码是写给机器的，这里练的是写给一个不欠你耐心的人。**
何时用：要写技术方案、周报月报、述职与晋升材料、故障复盘、分享稿与 PPT 大纲、给非技术同事的解释、要对方拍板的邮件与 IM 时。注意边界：给接口和代码写的说明书不算这里的活（那是文档类技能），这里处理的是「有个具体的人要读它，而且读完要给你一个回应」的场景。表里的子技能装了就直接调用，没装就按本页的精简方法做，并告诉用户可以在 SkillHub 搜对应 slug 安装。

## 动笔前的四问与三层骨架

```
读者是谁    他的职级、他背的指标、他对这件事已经知道多少
要他做什么  批准 / 出人 / 改优先级 / 只是知会——四个答案对应四种结构
他会在哪卡  术语、前提、跟他利益的关系；每个卡点提前拆掉，别指望他问
给他多久    30 秒读完的结论 + 3 分钟读完的正文 + 想追问的人才看的附录

第一屏  结论 + 你要的那个决定 + 代价，各一句。读完这屏他就能回你
第二层  为什么是这个结论——最多三条理由，每条挂一个可验证的数字或事实
第三层  被否决的备选与原因、风险与回滚、未知项。给较真的人看，也给半年后的你看
```

## 意图 → 方法 → 子技能

| 用户在说什么 | 先做什么 | 子技能（SkillHub slug） |
|---|---|---|
| 写技术方案、设计文档、RFC、立项材料 | 三阶段：先问文档类型与读者和期望效果 → 从未知最多的一节开始逐节精炼 → 丢给一个没有上下文的新会话做读者测试 | 文档协作写作 `doc-coauthoring-zh` |
| 方案写完了，怕评审会上被挑穿 | 自己先按 QA、SRE、安全、数据、成本五视角走清单，问题分「阻塞 / 建议 / 疑问」，缺的信息明确列为待补 | 技术方案评审 `tech-design-review` |
| 周报、月报、迭代报告、进展同步 | 从 git log 与工单聚合，按交付价值而不是提交流水重组，每条挂 commit 与工单号，缺口明写 | 迭代周报生成器 `iteration-report-git` |
| 述职、晋升答辩材料 | 先用同一个技能把一年的事实底稿捞全（它只出事实，不替你写绩效自评），再按下面「述职三段」重排成有判断的叙事 | 迭代周报生成器 `iteration-report-git` |
| 故障复盘报告、postmortem | 时间线先于分析：影响范围 / 时间线 / 根因 5 Why / 做对与做错 / 改进项带负责人与截止日与验收方式 | 线上排查简报 `incident-brief-sre` |
| 把讨论写成需求文档、再拆成任务 | Spec 模板（问题陈述、方案、用户故事、实现决策、测试决策、范围外）+ 垂直切片工单与阻塞关系 | 需求到 Spec 到任务 `spec-and-tickets-zh` |
| 我自己都没想清楚就要动笔 | 按设计树分轮拷问，每题附推荐答案；或一次只问一个问题并附上猜测，把「想要的」和「以为该要的」分开 | 需求盘问官 `grill-me-zh`、意图澄清访谈 `interview-me-zh` |
| 产品经理、老板、客服听不懂 | 短句不超过 20 字，一句一个意思，主动语态，一个概念只用一个词；只重讲不加新信息，结尾一句复述结论 | 大白话重讲 `re-pitch-zh` |
| 跨团队各说各的、同一个词两种意思 | 把统一语言与术语表当场写进 CONTEXT.md，模糊或重载的词提出精确说法，用具体场景压测边界 | 领域建模 `domain-modeling-zh` |
| 这个技术选型要不要记下来 | ADR 三条件同时成立才写：难以逆转、缺了上下文会让人费解、有真实权衡；必须写被否决的备选 | ADR 与技术文档 `docs-and-adr-zh` |
| 邮件或 IM 要对方给个说法 | 把你定不了的事变成编号问题清单，最重要的放最前（异步可能只有一轮），每题带答案占位与一行「为什么问」 | 决策问卷 `to-questionnaire-zh` |
| 休假、转岗、交给别人接手 | 不重复已有产物，只按路径引用；脱敏；必含下一步、验证命令、坑与未知 | 交接文档 `handoff-doc-zh` |
| PR 描述、版本说明、release notes | PR 写背景 / 改动 / 测试清单 / 风险与回滚 / 关联工单；对外的版本说明按 Keep a Changelog 分组，把提交翻译成用户视角 | PR 描述生成 `pr-description`、Changelog 生成器 `changelog-keep` |
| 技术分享稿、PPT 大纲、内部讲一讲 | 照下面「分享五段」搭骨架；仓库暂无对应技能 | —— |
| 写给 AI 或 Agent 看的规则与技能文档 | 上下文指针、上下文负担与认知负担、渐进式披露、每步的完成标准 | 给 Agent 写文档 `writing-for-agents-zh` |

## 述职三段与分享五段

```
述职三段（每个项目一遍，三段各一屏）
  1 问题  当时的难点与约束，为什么它非解不可，不解会怎样（有数字）
  2 判断  你做的那个别人可能不会做的选择，以及你排除了什么
  3 结果  指标前后对比 + 沉淀下来的东西（文档、规范、工具、带出来的人）

分享五段（40 分钟的稿子，先写这五句再写正文）
  1 钩子  听众明天就会遇到的那个具体麻烦
  2 错解  大多数人的第一反应，以及它为什么不够
  3 主线  一个概念讲到底，配一张自己画的图
  4 现场  一段能跑的最小例子（`python3 demo.py` 级别，20 行内），失败态也演一次
  5 回收  三条听完就能用的动作，写在最后一页不要念
```

## 输出契约

1. **结论在第一屏**：别让读者读到第三段才知道你要什么。
2. **每个数字有出处**：指标附时间窗与统计口径，代码附 commit 短 hash，拿不到就写「待确认」，不写「大幅提升」。
3. **一个概念一个词**：全文术语统一，同一个东西不要一会儿叫任务一会儿叫作业。
4. **写完做读者测试**：丢给一个没有上下文的新会话或真人，让他回答你预测读者会问的三个问题，卡住的地方回炉重写。
5. **不替人下结论**：该不该做、该不该批，给选项与代价；也不把推测写成事实，推测一律标注。

## 典型组合流程

- **一份要过评审的技术方案**：需求盘问官把隐含假设问干净 → 文档协作写作三阶段成稿 → 技术方案评审五视角自审、把「阻塞」项在会前改掉 → 读者测试 → 会上只讲第一屏。
- **述职周**：迭代周报生成器把一年的 commit 与工单捞成事实底稿 → 述职三段重排出判断 → 大白话重讲把每段压成非技术评委也能听懂的一句话 → 决策问卷提前准备评委最可能追问的五个问题。
- **故障之后**：线上排查简报出时间线与改进项 → Changelog 生成器写对外的版本说明 → 大白话重讲写给客服与业务方的一段话，三份互相引用同一条时间线。

## 不做什么

- 不写接口文档与代码注释，那是文档类与 OpenAPI 类技能的事。
- 不编数字、不编案例；没有的数据就留空并标注，宁可少写一条。
- 不替人发出去：邮件、述职材料、对外公告都由人自己按发送键。
- 不美化失败：复盘里做错的部分照写，改进项挂人挂日期挂验收方式。
- 不接触任何未脱敏的公司内部信息；示例一律用 GitHub / GitLab / Jira 与 example.com。

---
本系列全部开源（正文 CC BY 4.0，代码 MIT）：https://github.com/po-et/workbuddy-skills