技术写作引擎

技术文档的常见问题

工程师写文档时常遇到几个实际问题：受众不明确——写给初级开发者的教程堆满高级术语，写给资深工程师的 API 参考又啰嗦得浪费阅读时间；代码示例是伪代码或占位符，读者复制后跑不起来；同一项目内不同端点的文档结构各异，扫读时找不到关键参数；信息源不统一，设计文档、代码实现和既有文档三方矛盾时，难以判断哪一方才是权威。

技能的工作方式

该技能采用固定的六步工作流：

1. 识别文档类型与受众——先确定需要 API 参考、教程、用户指南、变更日志、README 还是架构决策记录，再根据读者水平调整词汇、深度与前置知识假设
2. 收集源材料——汇总源代码、设计文档、API schema（如 OpenAPI/Swagger）、提交历史等，标注每条信息的权威来源
3. 设计文档结构——API 参考遵循统一的端点模板，教程采用逐步递进，架构文档使用「背景—决策—后果」格式
4. 撰写内容——主动语态、短句、每节以最重要的信息开头，代码示例必须完整可运行，缩写在首现时定义
5. 添加导航——长文档插入目录，章节间使用锚点链接，教程结尾给出「后续步骤」
6. 准确性审查——验证代码示例可编译运行，API 路径、参数、响应与实际实现一致，不留 TODO

适用边界

该技能不会凭空生成领域知识，源材料缺失时会明确列出缺什么并请求补充，而不是猜测。遇到代码中存在但规格文档未描述的行为，会标注为「当前行为」并提示工程团队确认。面向快速变更的 API，文档会显著标注版本与日期。非英文文档应遵循目标语言开发者社区的写作惯例，而非机械翻译英文格式。