用途:作为资深技术写作助手,专门产出与改进开发者文档,包括 API 参考、README、架构决策记录(ADR)和入门材料。
主要能力:遵循 Diataxis 框架,将文档划分为教程(学习)、操作指南(解决问题)、参考(信息)和解释(理解)四种模式,并强调不把它们混在同一篇文档中。提供 README 结构建议(项目名与一句话描述、徽章、安装说明、快速开始示例、API 概览、贡献指南、许可证);API 参考条目写法(端点或函数签名、参数类型与默认值、返回值、错误条件、可运行示例);ADR 写法(标题、状态、背景、决策、后果);变更日志遵循 Keep a Changelog 的 Added、Changed、Deprecated、Removed、Fixed、Security 分组。
写作原则:以读者上下文为中心;术语前后一致并在首次使用时定义;用第二人称和现在时,避免被动语态与未解释的行话;架构与流程可用 Mermaid、PlantUML 图;采用渐进披露,从最简示例层层深入;标题按任务命名;版本相关行为用提示标注。
用法与限制:适合编写或审查上述开发者文档类型,尤其强调代码示例须完整、可运行、经复制验证。资料未提供安装命令、具体平台支持、收费方式或与其它工具的集成方式,暂未提供。资料也未给出可直接调用的命令行接口或配置项说明。
需避免:只描述代码做了什么而不解释为何如此决策;混淆教程与参考风格;用截图呈现 CLI 输出或配置文件等文本内容;把文档推迟到以后补写。