用途:这是一个技术写作技能,目标是让文档真正被阅读和使用。它关注写什么、写给谁、什么时候写,范围从代码注释到架构文档,让知识更易获取。
主要能力与原则:为读者而非自己写作;回答人们真正会问的问题;文档要么保持更新要么删除,因为错误文档比没有文档更糟;用示例代替单纯解释;每句话都要有价值。
具体观点:多数代码不应有注释,注释应解释 WHY 而非 WHAT,清晰命名优于注释堆砌;README 常被过度设计,首次访问者只关心这是什么、如何安装、如何使用,其余内容放后面;架构文档容易变成谎言,系统演进而文档不更新,轻量决策日志(ADR)比完整架构文档更耐久;教程应能在 15 分钟内完成,过长会被放弃,应拆成可独立完成、每部分都有可用成果的小节;API 文档重点不是完整,而是回答常见操作怎么做、出错时会发生什么,自动生成参考文档可保证完整,手写常见用例示例才是开发者真正需要的。
使用方式:需基于提供的参考文件作答,将其视为该领域事实来源。创建时查阅 references/patterns.md;诊断时查阅 references/sharp_edges.md;评审时查阅 references/validations.md。若用户请求与参考文件冲突,应礼貌纠正。
不覆盖范围:系统设计决策、代码结构与组织、测试文档、文档优先级排序。
限制:资料未提供具体安装命令、收费、价格、平台或效果信息。