技术写作深度工作流

技能文档

---
name: techwrite
title: 技术写作深度工作流
category: 内容创作
description: 技术文档写作深度工作流，按受众与目标定义、大纲与范围、核心内容起草、示例与边界情况、清晰度审校、发布与维护六阶段推进，优化清晰度、正确性与深度适配，覆盖开发者文档、迁移指南、RFC、架构说明、故障手册与技术文章。当用户需要撰写或改写技术文档、设计笔记、内部指南、RFC 或公开技术文章时触发。触发词：技术文档、写作润色、RFC、设计文档、开发者文档、文档改写。
---

# 技术写作深度工作流

技术写作成功的标准是**读者能照着行动**或**据此决策**而少有困惑。优化目标是**清晰、正确、深度得当**——而不是字数。

## 技能工作流

按六阶段推进：明确受众与目标 → 大纲与范围 → 起草核心内容 → 示例与边界情况 → 清晰度审校 → 发布与维护。若团队有现成模板或风格指南，先向用户索取。

### 步骤1：明确受众与目标

**目标**：确定一个主要读者画像；一个**成果**。

需要回答：

1. **谁**在读（新员工、合作方工程师、SRE、API 终端用户）？
2. **要完成什么任务**：排查问题？集成 API？评审通过设计？
3. **约束条件**：字数限制、法务审核、后续本地化？

**反面目标**："面向所有人"通常等于**谁都不满意**——优先分层文档（概览 + 深度链接）。

**退出条件**：写出**成功句**："读完后，读者能够___。"

### 步骤2：大纲与范围

**目标**：**结论先行（BLUF）** + 符合读者心智模型的**章节结构**。

做法：

- **开头**：背景 + 成果 + 前置条件
- **中间**：操作步骤 **或** 概念模型——每篇选定一种主模式
- **结尾**：故障排查、FAQ、链接、变更记录

范围控制：

- 对模糊主题给出**范围内 / 范围外**声明框
- 快速迭代的产品标注**版本**与**最后审阅时间**

**退出条件**：大纲通过评审；**顺序**符合读者旅程（通常是先走通主路径）。

### 步骤3：起草核心内容

**目标**：**精确、可扫读、诚实**。

文风：

- **短句**；操作说明用**主动语态**（"点击…"、"运行…"）
- 术语**首次出现时定义**；大型文档附**术语表**
- **避免**没有评判标准的模糊形容词（"强大的"、"无缝的"）

结构信号：

- **标题**描述内容本身；**列表**用于并列项
- **编号步骤**用于顺序敏感的操作

**退出条件**：完成第一遍全文——**允许粗糙**，精确优先于润色。

### 步骤4：示例与边界情况

**目标**：好的示例**减少工单**；边界情况**建立信任**。

示例要求：

- **最小完整**可运行片段；**真实感**命名；给出**预期输出**
- 常见报错时展示**失败示例**——并附**修复方法**

边界情况：

- 权限、限流、幂等性、向后兼容
- 必要时给出**"看到 X 就做 Y"**的排查表

**退出条件**：操作类文档至少有一条**端到端**路径在全新环境跑通。

### 步骤5：清晰度审校

**目标**：消除**歧义**与**隐藏假设**。

检查清单：

- **歧义代词**（"它"、"这个"）——替换为具体名词
- **隐含步骤**——改为显式
- **图表**：箭头带标签；附**替代文本**保证可访问性
- **链接**：避免失效锚点；优先**稳定** URL

评审方式：

- **同行评审**保技术准确；入门类文档找**非专家**试读

**退出条件**：另一位读者无需追问即可照做——或追问已沉淀为 **FAQ**。

### 步骤6：发布与维护

**目标**：文档会**过时**——规划更新机制。

做法：

- 设置**负责人**字段；关键路径设**定期评审**节奏
- 平台频繁变化时附**变更记录**或页面历史
- 废弃旧页面时设置跳转

## 最终检查清单

- [ ] 受众与成功成果明确
- [ ] 大纲符合读者旅程
- [ ] 操作步骤有编号；概念与步骤分离
- [ ] 必要处有示例与失败示例
- [ ] 已做歧义审校；图表可访问

## 指导技巧

- 优先用**具体名词**而非抽象概念（"数据库主键"而非"系统"）。
- 用户贴草稿时做**外科手术式**修改——保持原行文风格，除非影响清晰度。
- 面向**非母语读者**时避免习语和文化专属笑话。

## 特殊情况处理

- **营销色彩过重的需求**：把**事实**与定位话术分开；对高风险表述打标。
- **涉法敏感内容**：建议专家评审；非资质范围内不代拟具约束力的法律文本。

使用说明

# 技术写作深度工作流

六阶段技术文档写作工作流：受众与目标 → 大纲与范围 → 起草 → 示例与边界 → 审校 → 发布维护，让读者读完就能行动或决策。

## 使用

```text
帮我把这份设计笔记改写成面向合作方工程师的接入文档：（粘贴内容）
```

```text
我要写一篇 API 迁移指南，按技术写作工作流带我走一遍
```

## 工作原理

每阶段有明确的退出条件（如步骤1的"成功句"、步骤4的"端到端跑通"），先定读者画像与成果再动笔；正文强调短句、主动语态、术语首现即定义；最后按检查清单消歧义、补替代文本、设负责人与评审节奏，防止文档过时。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。