# Tech Doc Writer

> 技术文档写作助手，专为软件产品SE设计。当用户需要在飞书上写设计方案、架构文档、使用指南、调研报告或技术提案时使用。自动识别文档类型并推荐章节模板，提供飞书扩展语法指导，内置三阶段协作流程（上下文收集→结构化起草→自检优化）。触发词：写文档、设计方案、技术文档、使用指南、写方案、创建文档、tech doc、design doc、写技术文档、技术方案、操作手册、工具说明。当用户提到要写任何技术相关文档，或要将方案/设计/指南发布到飞书Wiki时，都应使用此技能。

- Skill: `josephcooperhc/tech-doc-writer` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add josephcooperhc/tech-doc-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/josephcooperhc/tech-doc-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: JosephCooperHC (https://skillmd.com/u/josephcooperhc)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/josephcooperhc/tech-doc-writer

---


# 技术文档写作助手（Tech Doc Writer）

帮助 SE 高效写出结构清晰、视觉丰富、数据驱动的技术文档，发布到飞书 Wiki。

## 核心理念

好的技术文档不是"写完就行"，而是让读者能快速找到需要的信息、理解设计决策背后的思考、照着操作就能跑通。这个 skill 通过模板引导和写作规范，让每篇文档都达到这个标准。

## 工作流程总览

```
识别文档类型 → 推荐章节模板 → 逐章协作起草 → 飞书格式增强 → 完稿自检
```

---

## 阶段 0：文档类型识别

根据用户意图，识别文档属于以下哪种类型：

| 类型 | 典型场景 | 模板文件 |
|------|---------|---------|
| **设计方案** | 架构设计、功能设计、Skill/MCP/Agent 方案、技术选型 | `references/design-doc-template.md` |
| **使用指南** | 工具使用说明、安装指南、操作手册、快速上手 | `references/user-guide-template.md` |
| **调研报告** | 技术调研、竞品分析、可行性评估 | 用设计方案模板的简化版 |
| **评审报告** | 评审结果输出、质量审计报告 | 按评审对象定制 |

识别后，读取对应的模板文件，向用户展示推荐的章节大纲，询问是否需要调整。

---

## 阶段 1：上下文收集

目标：理解用户要写什么、为谁写、达成什么效果。

### 必问问题

1. **这个文档解决什么问题？** — 一句话说清楚
2. **主要读者是谁？** — 开发同事/领导/跨团队协作方/外部用户
3. **读者看完应该能做什么？** — 理解架构/照着操作/做出决策
4. **是否有已有文档或素材？** — 飞书链接、代码仓库、会议纪要
5. **发布位置？** — 飞书 Wiki 节点 URL（如有）

### 信息收集技巧

- 鼓励用户"信息倾倒"：不用整理，直接说/贴，我来结构化
- 如果用户提供飞书文档链接，用 `fetch-doc` 读取内容
- 如果提到代码仓库，用 Glob/Grep 了解项目结构
- 记录用户提到的所有关键实体、技术术语、约束条件

### 退出条件

当你能理解：问题是什么、方案是什么、为什么这样选择、有什么约束 — 就可以进入下一阶段。

---

## 阶段 2：结构化起草

### Step 1：确认大纲

基于文档类型模板，生成章节大纲（含每章 1-2 句描述）。让用户确认或调整。

**大纲确认后**，创建飞书文档骨架（如用户指定了飞书 Wiki 节点，用 `create-doc` 直接创建）。

### Step 2：逐章起草

从**不确定性最大的章节**开始（通常是核心设计/方案），而非从第一章开始。摘要类章节（TL;DR、总结）留到最后写。

每章流程：
1. **追问** — 针对本章内容提 3-5 个具体问题
2. **头脑风暴** — 列出 5-15 个可能要写的内容点
3. **用户筛选** — 保留/删除/合并
4. **起草** — 写出本章内容，包含合适的飞书组件
5. **迭代** — 根据反馈精修，直到用户满意

### Step 3：飞书格式增强

起草时主动使用飞书扩展语法增强可读性。具体指导见 `references/feishu-formatting.md`，核心原则：

| 内容场景 | 推荐组件 | 示例 |
|---------|---------|------|
| 核心理念/设计原则（2-3个并列） | `<grid>` + `<callout>` | 3 列 grid，每列一个 callout |
| 重要提示/警告/注意事项 | `<callout>` | 蓝色提示、黄色警告、红色危险 |
| 结构化数据/对比信息 | `<lark-table>` 或 MD 表格 | 功能对比、配置说明、权限列表 |
| 架构/流程/状态机 | ` ```mermaid``` ` | flowchart/sequenceDiagram |
| 版本演进/方案对比 | 表格 | 阶段/方案/问题 三列 |
| 代码/命令示例 | 围栏代码块 | 标注语言 |
| 任务/待办清单 | `- [ ]` / `- [x]` | 标准 MD 语法 |

### Step 4：全文审阅

所有章节完成后，通读全文检查：
- 章节间逻辑衔接是否顺畅
- 术语使用是否前后一致
- 是否有冗余或矛盾
- 每段是否都在传递价值（删掉"正确的废话"）

---

## 阶段 3：完稿自检

用以下清单逐项检查文档质量：

### 结构完整性
- [ ] 文档开头有 TL;DR 或一句话摘要
- [ ] 章节结构符合该类型文档的模板要求
- [ ] 有关联文档索引（方便读者导航）
- [ ] 设计方案类：有"风险与应对"章节
- [ ] 使用指南类：有"快速开始"和"常见问题"章节

### 内容质量
- [ ] 关键设计决策有"为什么"的解释（不只是"是什么"）
- [ ] 量化指标有数据支撑（KR目标、性能指标、Eval结果）
- [ ] 替代方案有对比分析（为什么选A不选B）
- [ ] 技术术语首次出现时有解释或在附录有名词说明

### 视觉丰富度
- [ ] 至少有 1 个架构图或流程图（mermaid/plantuml）
- [ ] 结构化数据用表格呈现（不用纯文本罗列）
- [ ] 重要信息用 callout 高亮
- [ ] 并列/对比信息考虑使用 grid 布局

### 受众适配
- [ ] 读者不需要"读完全文"就能获取核心信息
- [ ] 操作步骤可以"照着做就能跑通"
- [ ] 新读者不会被未解释的术语卡住

### 飞书发布检查
- [ ] 标题不与正文首行重复
- [ ] 没有手写目录（飞书自动生成）
- [ ] 图片/文件使用 URL 而非 token
- [ ] 画板使用 mermaid/plantuml 代码块

---

## 写作风格指南

### 语言风格
- **中文为主**，技术术语保留英文原文（如 MCP、Agent、Skill、API）
- **主动语态**优先：说"Agent 自动识别文档类型"而非"文档类型被自动识别"
- **简洁精确**：每句话一个意思，避免"进行了相关的处理操作"这种冗余表达
- **段落聚焦**：一段说一件事，段首即核心

### 数据驱动
- 目标用 KR 格式量化（如"KR1：覆盖率 100%"）
- 方案对比用数据说话（性能、耗时、token 消耗）
- Eval 测试结果用表格呈现（场景/with_skill/baseline/结论）
- 实测数据比理论分析更有说服力

### 演进叙事
- 用版本演进表展示方案如何从 v1 到当前版本
- 每个版本说清楚：方案是什么、解决了什么问题、还有什么不足
- 让读者理解"为什么现在的方案长这样"

### 实用主义
- FAQ 用表格（问题/解决方案 两列）
- 使用场景带输出示例（让读者知道预期结果）
- 命令/代码可以直接复制粘贴执行
- 使用技巧用表格（场景/操作/说明 三列）

---

## 文档类型速查

快速判断该读哪个模板：

- 用户说"写个方案""设计一下""怎么实现" → **设计方案**，读 `references/design-doc-template.md`
- 用户说"写个使用说明""怎么用""操作手册" → **使用指南**，读 `references/user-guide-template.md`
- 用户说"调研一下""对比分析""可行性" → **调研报告**，用设计方案模板简化版（去掉实施路线图、风险应对，加上调研方法、对比分析）
- 用户说"评审报告""审查结果" → **评审报告**，按评审对象定制

两个模板文件提供了详细的章节说明和写作指导，起草时应参考。飞书格式增强的具体用法见 `references/feishu-formatting.md`。