documentation

文档 skill 概览

documentation skill 是做什么的

documentation skill 适合帮你按 Diátaxis 模型来创建、重组和审阅技术内容：教程、操作指南、参考文档和说明文档。当你需要的不只是一个通用写作提示，而是一个能贴合用户意图的文档结构时，它尤其有用。

适合谁使用

如果你在做产品文档、API 文档、上手流程或内部开发者文档的技术写作，这个 documentation skill 很适合你。它尤其适用于你已经了解主题，但需要帮助来判断文档类型、梳理大纲，或者修正那些会让读者困惑的文档。

它的优势在哪里

它的核心价值是分类和结构，而不只是生成文字。documentation install 的设计目标，是帮助你把学习内容和任务内容分开，保持参考资料的客观性，并减少把解释、流程和 API 细节混在一页里的常见错误。

如何使用 documentation skill

安装并打开正确的文件

运行 npx skills add mcollina/skills --skill documentation 安装 documentation skill。先从 SKILL.md 开始，再查看 tile.json，了解简要摘要和元数据。因为这个 repo 里没有配套的 rules/、references/ 或 scripts/ 文件夹，所以核心行为主要来自主 skill 文件本身。

把模糊需求改写成有效提示词

这个 skill 在你提供文档目标、受众和源材料时效果最好。比如，不要只说“帮我写 API 文档”，而应该问：“为需要使用 API key 认证我们 API 的新后端工程师创建一篇 how-to guide；包含前置条件、设置步骤、一个成功示例和常见失败场景。” 这类输入能让 documentation usage 保持聚焦，也会让输出更容易直接发布。

先用 Diátaxis 做判断

在要内容之前，先判断用户需要的是 tutorial、how-to guide、reference page 还是 explanation。tutorial 通过实践来教学；how-to guide 解决一个具体任务；reference 记录事实；explanation 解释概念和取舍。如果跳过这一步，输出可能读起来不错，但仍然达不到 documentation guide 的标准。

更好的输出建议工作流

先读源产品笔记，再决定目标文档类型；如果范围较大，先让 skill 生成大纲，再生成完整初稿。对于 Technical Writing 相关的 documentation，这通常比一上来就要整页内容更有效，因为你可以更早修正范围、术语和缺失的前置条件。

documentation skill 常见问题

这比普通提示词更好吗？

是的，尤其在结构很重要的时候。普通提示词可以写出文本，但 documentation skill 的重点是先帮你选对文档模式，而这往往才是技术写作里真正的问题。

什么时候不该用它？

不要把它用于营销文案、release notes 或观点文章。另一种不适合的情况是：你只需要一个不依赖上下文的快速答案，因为 documentation 工作通常取决于受众、约束条件以及被记录的任务本身。

对新手友好吗？

友好，只要你能用简单语言把目标说清楚。新手在使用 documentation skill 时，如果能说明产品、读者层级，以及需要记录的具体动作或概念，往往能得到最大收益。

适合 developer docs 和 API docs 吗？

适合。documentation skill 很适合 API documentation、setup guides 和内部 developer docs，尤其是在你需要把参考材料和教程或 how-to guides 分开的时候。

如何提升 documentation skill

给 skill 提供合适的原始材料

最好的结果来自具体输入：产品名称、目标读者、文档类型、当前状态，以及读者需要达成的精确结果。比如，“为首次集成的用户更新我们的 authentication docs；他们需要生成 token 并测试一条请求”就比“帮我改进文档”强得多。

提前说明约束条件

一开始就说清平台、版本、语气、术语和任何政策限制。如果你的 documentation install 必须符合现有风格指南、特定 SDK 或 docs site 格式，就要在生成之前说明；否则输出可能结构正确，但仍然无法直接使用。

警惕最常见的失败模式

最大的问题通常是选错 Diátaxis 类型、把 explanation 混进流程步骤里，以及用 tutorial 的语言去写 reference 内容。如果第一版看起来太宽泛，可以要求拆成独立页面、补全更明确的前置条件，或者重写，把任务步骤里的概念性填充删掉。

用有针对性的修改逐步迭代

第一轮完成后，可以一次只要求一个改动来优化 documentation skill 的输出：“把这篇改成纯 how-to guide”“补上缺失的前置条件”“把示例改成 API reference 风格”或“按高级用户重写”。这种迭代方式通常比泛泛要求整体润色，更能做出高质量的 documentation guide。