name: 实用写作 description: 该技能应在撰写技术内容时使用，模仿Hunt/Thomas（《程序员修炼之道》）和Joel Spolsky（Joel on Software）的风格。适用于创建清晰、引人入胜、可操作的技术文章、文档、教程或解释性内容。
实用写作技能
写作风格基于技术沟通大师：Andy Hunt、Dave Thomas（《程序员修炼之道》）和Joel Spolsky（Joel on Software）。这种技能将技术内容转化为引人入胜、令人难忘的散文。
何时使用此技能
此技能适用于：
- 创建技术博客文章、文章或论文
- 撰写需要个性的文档
- 向开发者解释复杂概念
- 制作教程或操作指南
- 撰写“经验教训”或事后分析内容
- 任何应被阅读而不仅仅是参考的技术写作
核心理念
“‘差不多对’和‘对’的区别就像萤火虫和闪电的区别。” — Mark Twain（被Pragmatic Programmers引用）
技术写作不必枯燥。最好的技术作家使复杂想法显得显而易见，在抽象理论之前使用具体例子，并将读者视为聪明的同事。
10个核心技巧
参考完整技巧指南：techniques.md。
1. 具体先于抽象
始终从具体例子开始，然后提取原则。
❌ "依赖注入是一种设计模式，其中依赖关系被传递给对象，而不是由对象创建。"
✅ "想象你的类需要一个数据库连接。你可以自己创建它：
def initialize
@db = Database.new("localhost:5432")
end
但现在你的类被限制在那个特定的数据库上。如果你想用假数据库测试怎么办？如果生产环境使用不同的主机怎么办？
相反，将其作为参数接受：
def initialize(db)
@db = db
end
这就是依赖注入。很简单。"
2. 物理类比
将抽象概念映射到读者已经理解的物理体验。
查看类比模式：examples.md：
- 软件抽象 → 物理工具
- 代码模式 → 架构模式
- 系统设计 → 日常系统（邮政服务、餐厅）
3. 对话式语域
写作就像在白板上向聪明的同事解释一样。
对话式语域的标记：
- 缩略语（不要、不会、不能）
- 直接称呼（你、你的）
- 问题（但如果…？为什么这很重要？）
- 旁白（顺便说一句、附带地）
- 承认（老实说，我不确定，这取决于）
4. 幽默作为架构
策略性地使用幽默，而不是装饰性地：
- 令人难忘的钩子（“好代码是最好的文档”）
- 复杂解释后的紧张缓解
- 自嘲以建立融洽关系
- 荒诞的例子以突出不良模式
5. “啊哈！”结构
构建到顿悟时刻：
- 呈现一个熟悉的问题
- 展示常见的（有缺陷的）方法
- 揭示为什么失败
- 呈现洞察
- 展示更好的方式
- 连接回原则
6. 短段落，多变长度
- 段落不超过4句话
- 交替使用较长的解释和有力的单句
- 使用单句段落进行强调
就像这样。
7. 代码作为证据
代码示例应该：
- 可运行（除非必要，不使用伪代码）
- 最小化（只显示重要的部分）
- 从损坏到修复的进展
- 只对不明显的事物添加注释
8. 原则框
在具体探索后，框出原则：
提示 23: 始终为并发设计 允许并发，你将设计出更清晰的接口，假设更少。
9. 友好的警告
当讨论陷阱时：
- 承认你也犯过这个错误
- 解释为什么诱人
- 展示后果
- 提供逃生舱口
查看常见技术写作错误：anti-patterns.md。
10. 回调
通过连接回开头的例子或问题来结束。闭环。
声音特征
句子模式
- 平均长度：15-20个单词
- 简单、复合、复杂的混合
- 每3-4段一个问题
- 关键点的直接陈述
词汇
使用：具体、日常的词汇 避免：没有解释的行话、流行语、公司用语
语气
- 自信但不傲慢
- 好奇和探索性
- 实用和结果导向
- 偶尔不敬
应用技能
对于博客文章
- 以问题或场景开头
- 探索混乱的中间部分
- 揭示洞察
- 展示解决方案
- 提取原则
- 回调到开头
对于文档
- 从读者想要做什么开始
- 展示最简单的工作示例
- 扩展选项和边缘案例
- 解释“为什么”在“如何”之后
对于教程
- 清晰陈述目标
- 先展示最终结果
- 以小的、可测试的步骤构建
- 解释错误，而不仅仅是成功
质量检查清单
发布前，验证：
- [ ] 以具体例子或场景开头
- [ ] 关键概念的物理类比
- [ ] 全程对话式语气
- [ ] 至少有一处幽默或轻松时刻
- [ ] 原则被框出或高亮
- [ ] 代码示例最小且可运行
- [ ] 段落不超过4句话
- [ ] 回调到开头
参考文献
- techniques.md - 带示例的完整技巧指南
- examples.md - 前后转换
- anti-patterns.md - 技术写作的七大死罪
- sources.md - 原始资料