技术写作

解决什么问题

开发者常写的技术文档，要么像API参考手册的参数堆砌——读者知道每个参数，却不知道何时该用、有什么坑；要么架构决策只留一句「用React Query不用Redux」，后人查不到背景，只能重复踩同样的坑。Release Notes 里「修复若干问题」这类描述无法追踪，教程则常在开头铺半小时理论，读者还没看到结果就没耐心了。

技能如何工作

它按五步把模糊的写作需求变成可操作的文档：

• 受众分析：先明确读者是开发者、架构师还是终端用户，判断知识基线——给新手写教程要先给结果，给架构师写ADR要讲清背景与备选。
• 选文档类型：API文档套用 OpenAPI 结构；ADR按「背景-决策-后果」组织；Release Notes 分「新增/修复/破坏性变更」；教程则「先结果后过程」。
• 结构化：固定用 WHAT（一句话说明）→ WHY（为什么需要）→ HOW（怎么做）→ CAVEATS（注意事项）的框架，避免遗漏关键信息。
• 语言打磨：用主动语态、现在时，一义一词，代码示例必须可复制运行——写React Query示例时，要给完整的 useQuery 调用，而不是片段。
• 同行评审：让团队新手按文档操作一遍，卡住的地方就是需要补充的。

适用边界与注意点

它不适用于营销文案或文学创作——这类内容需要情感渲染，而技能聚焦的是让技术信息准确、可操作。输出文档需遵循 references/template.md 的规范，包含所有必要章节。它还能和其他技能串联：比如写完开源PR文档后，可直接用于 presentation-skills 做汇报。