technical-documentation

技术文档方法论

技术文档是工具与用户之间的接口。本方法论涵盖如何编写文档，使其能够回答读者的问题、不妨碍读者使用，并在项目不断演进时仍易于维护。

技术写作者的职责范围

由你负责	不由你负责
API 文档——端点参考、参数、示例	编辑和长篇叙述内容——由编辑职能负责，不属于本技能的范围
README 编写——项目概述、快速入门、配置	品牌宣传和营销文案——由品牌设计师负责
CLI 文档——帮助文本、用法模式、退出代码	代码架构决策——由软件架构分析负责
面向 Agent 的文档——AGENTS.md、技能文档	项目路线图和产品愿景——由产品经理负责
参考文档——配置文件、故障排除、架构	性能优化指导——由系统化调试 / SRE 负责
文档站点结构——信息架构、交叉引用、搜索	代码质量和标准——由 QA 方法论 / QA 工程师负责

参考文件

参考资料	加载时机
references/readme-patterns.md	编写或重构 README 时——每份 README 必需的章节、快速入门模式、安装方式、配置文档
references/api-documentation-cli-help.md	编写 API 文档（端点结构、参数约定、示例设计、身份验证模式、OpenAPI 注解）以及设计 CLI 帮助文本（用法行、标志、退出代码、子命令层级、man 页面）时
references/agent-facing-docs.md	编写 AGENTS.md 和技能文档时——触发模式、加载顺序、输出约定、交叉引用
references/information-architecture.md	构建文档站点时——渐进式信息呈现、交叉引用、搜索优化、维护策略

相关技能

• documents — 根据文档内容制作办公格式的交付物（PDF、Word、Excel、PowerPoint）；文档站点和标记语言约定仍归本技能负责。

核心原则

记录接口，而非实现——用户需要知道函数的功能、预期输入和返回内容。内部实现方式应留在源代码中。

优秀的文档能回答读者的问题——不同读者带着不同的问题而来。想要入门？查阅参考资料？排查问题？组织文档，让每位读者都能迅速找到答案。

全面详尽胜过叙事脉络——技术文档不是文章。读者会跳到自己需要的部分。涵盖每个参数、每种边缘情况、每个错误代码。不要跳过枯燥的部分——人们往往正需要这些内容。

每份文档都是一项负担——你编写的每个页面都需要维护。宁可记录得少一些，但更加完整，也不要面面俱到却质量低下。维护成本与文档覆盖面成正比。

展示胜于讲述——每个概念都需要一个完整示例。每个 API 端点都需要请求和响应。每个配置选项都需要完整示例，而不仅仅是描述。

可移植性

本技能有意保持对宿主环境的中立。请使用 Agent 的常规机制加载此处列出的参考资料、模板和脚本。不要假设存在特定的配置文件系统、任务编排器、记忆服务或响应交接格式。