问题：当你的智能体文档变成路障
你构建了一个功能强大的AI智能体。它能自动化任务、回答问题，并与各种API集成。但有一个持续存在的问题正在减缓用户的采用速度，并让他们感到沮丧：文档。它是一团混乱的混合体——一个过于模糊的快速入门指南、一个读起来像原始API转储的参考部分，以及零散的、与实际任务脱节的解释性内容。新用户在试图为一个常见问题寻找简单操作指南时迷失了方向。有经验的用户无法快速查找某个特定参数。你知道文档需要改进，但每次尝试编写都显得临时起意，结果导致更多的不一致性。
这不仅仅是一个美观问题。糟糕的文档直接影响你的智能体的实用性。它增加了支持请求，因为用户会问一些本应在文档中得到解答的问题。它减慢了上手速度，因为开发者在理解如何配置或扩展智能体时遇到困难。它甚至可能导致误用，用户因为没有清楚地解释预期工作流程而错误地应用智能体。核心问题在于缺乏系统性的方法。将“文档编写”作为一个单一的、笼统的任务来处理，会导致文档试图面面俱到，最终却对谁都没有真正的用处。
一个好的解决方案需要从一开始就施加一个清晰的、以用户为中心的结构。它应该迫使你在开始写作之前思考每篇文档的目的。这是给初学者的课程吗？是解决特定错误的食谱？是给专家的技术词典？是解释“为什么”的概念性讨论？没有这个框架，你很可能会产出组织混乱、不完整且无法满足用户在不同阶段不同需求的文档。
引入结构化方法：Diátaxis框架
解决这个问题的一个实用方法是采用Diátaxis技术文档编写框架。Diátaxis是一种系统化方法，它识别出四种不同类型的文档，每种都服务于特定的用户需求，并要求不同的写作风格。该框架基于一个原则：文档的结构必须围绕用户与知识的关系来构建。
Diátaxis的四个象限是：
- 教程（Tutorials）： 以学习为导向。它们是实用的课程，逐步引导新手取得成功的结果。目标是教学，而不仅仅是告知。你的AI智能体的一个教程可能是“构建你的第一个自动化报告生成器”。
- 操作指南（How-to Guides）： 以问题为导向。它们是提供解决特定现实世界问题步骤的“食谱”。它们假设用户具备一定知识，并专注于实现目标。例如：“如何配置智能体使用自定义LLM端点”。
- 参考（Reference）： 以信息为导向。它提供关于“机械装置”——你的智能体API、配置选项和命令语法——的准确、简洁的技术描述。它是一本字典或手册，旨在被查阅，而不是从头到尾阅读。
- 解释（Explanation）： 以理解为导向。它提供背景、上下文和澄清。它讨论主题和概念以加深理解。例如：“理解智能体的记忆架构”或“我们为何选择特定的工具调用协议”。
Diátaxis的力量在于其清晰性。通过将你的文档分类到这四个象限中，你立即知道要写什么、如何写以及为谁而写。你不再试图将教程的叙述塞进参考表中，或者将关键的操作步骤埋藏在冗长的解释里。
documentation-writer技能如何实现此框架
如果你正在构建AI智能体，并希望系统地应用Diátaxis，你可以利用一个为此目的设计的专门技能。documentation-writer技能是一个严格遵循Diátaxis框架运行的专家技术写作者角色。它不是一个能为你自动写出完美文档的魔法棒，而是一个强制执行严谨工作流程的结构化协作者。
当你使用这个技能时，它不会直接开始写作。它遵循一个定义好的流程：
-
确认与澄清： 它首先会问你一些有针对性的问题，以确定你所需文档的确切性质。它会坚持澄清：
- 文档类型： 这是教程、操作指南、参考还是解释？
- 目标受众： 这是为谁写的？新手开发者？DevOps工程师？产品经理？
- 用户目标： 读者应该获得什么具体任务或理解？
- 范围： 应该包括什么，同样重要的是，应该排除什么？
-
提出结构： 根据你的回答，它会生成一个详细的提纲——一个带有简要描述的目录。这迫使你在撰写任何正文之前就结构达成一致，防止范围蔓延并确保对齐。
-
生成内容： 只有在你批准提纲之后，它才会继续以格式良好的Markdown编写完整的文档，遵循清晰、准确和以用户为中心的原则。
这个工作流程是关键。它将文档编写从一个模糊、令人生畏的任务转变为一系列具体的、可管理的步骤。它确保每篇文档都有明确的目的和受众。
评估此技能是否适合你的工作流程
这个技能是一个用于结构化思考和起草的工具。在以下情况下它特别有用：
- 你发现自己反复编写同一种类型的文档（例如，总是以一个模糊的“概述”部分开始）。
- 你的文档在项目不同部分之间感觉不一致，无论是语气、深度还是组织方式。
- 你需要为多个受众编写文档（例如，同时面向终端用户和扩展智能体的开发者），并希望确保每个受众获得正确类型的内容。
- 你在团队中工作，需要一个共同的框架来分配文档任务并保持质量。
然而，理解它的边界很重要。这个技能是一个写作和结构化助手。它不：
- 分析你的代码库以自动生成API参考文档。你必须提供技术细节。
- 取代对技术准确性的需求。 你是主题专家；该技能帮助你有效地传达这种专业知识。
- 处理图形设计、网站构建或发布。 它输出Markdown内容。
使用前需检查的事项
如果你考虑将此技能集成到你的工作流程中，以下是一些需要检查和考虑的实际事项：
1. 了解来源和上下文
该技能是awesome-copilot仓库的一部分，这是一个为GitHub Copilot准备的大量提示和技能集合。该仓库拥有显著的社区关注度（超过3.5万星），表明其广泛的兴趣和使用。技能本身定义在一个SKILL.md文件中，你可以直接查看。它根据仓库的许可证进行许可。没有迹象表明技能作者与Diátaxis框架创建者有关联；它是该框架原则的一个实现。
2. 测试澄清工作流程
这个技能最有价值的部分是其初始提问阶段。在将其用于关键文档之前，先用一个低风险的请求测试一下。看看它如何探究文档类型、受众、目标和范围。它的提问思路是否帮助你更清晰地思考你需要什么？如果它的问题感觉多余或偏离主题，它可能不符合你的思维风格。
3. 准备好你的技术输入
请记住，该技能是一个写作者，而不是读心者。对于参考文档，你需要提供原始的API规范、配置键或命令选项。对于操作指南，你需要描述问题和解决步骤。技能输出的质量直接取决于你在澄清和提纲阶段提供给它的信息的质量和具体性。
4. 考虑输出格式
该技能输出Markdown。这对于存放在Git仓库、静态网站生成器（如MkDocs、Docusaurus或Jekyll）或像GitHub Pages这样的平台上的文档来说是理想的。如果你的文档系统需要不同的格式（例如reStructuredText、AsciiDoc或特定于CMS的格式），你将需要处理转换。
5. 安全性
该技能运行在“低”安全级别，意味着它被设计为一个文本生成助手，不需要提升权限或访问敏感系统。它本身不执行代码或访问外部网络。它的主要功能是根据你的指令来组织和编写文本。与任何生成内容的工具一样，你应始终在发布前审查输出的准确性，尤其是技术细节。
一个实际例子：从混乱到结构
想象一下，你需要为你的AI智能体记录一个新的“网络搜索”功能。
没有框架时， 你可能会写一个标题为“网络搜索功能”的单一文档，试图解释它是什么、如何启用、列出所有参数，并讨论隐私影响——所有这些都写在一个冗长、散乱的页面里。
使用documentation-writer技能时， 过程会有所不同。你会先告诉它你需要记录网络搜索功能。它会问：“这是什么类型的文档？”你可能会意识到你实际上需要三份文档：
- 一份教程 (
tutorial_web_search.md)：“赋予你的智能体网络力量：分步指南”。这将引导用户完成启用功能、运行他们的第一个搜索增强查询以及解释结果的步骤。 - 一份操作指南 (
howto_restrict_search_domains.md)：“如何将网络搜索限制在特定的可信域内”。这将为有特定安全需求的用户提供确切的配置步骤。 - 一份参考 (
reference_web_search_config.md)：“网络搜索配置参考”。这将是一个简洁的表格，列出所有配置参数、其类型、默认值和描述。
通过强制进行这种分类，该技能帮助你创建聚焦、可查找且适合用途的文档。用户可以直接找到他们需要的课程、食谱或字典。
结论：将文档作为一个系统来构建
好的文档不是事后才考虑的事情；它是你的AI智能体可用性的核心组成部分。Diátaxis框架提供了一个经过验证的、合乎逻辑的结构来组织你的写作工作。documentation-writer技能提供了一种实用的方式来实现该框架，它作为一个严谨的写作伙伴，强制执行从澄清到提纲再到最终草稿的清晰工作流程。
它不会自己写出完美的文档，但它可以通过确保每篇写作都有明确的目标和受众，显著提高你文档的一致性、清晰度和用户导向性。如果你当前的文档编写过程感觉混乱，采用像这样的结构化方法是对你智能体长期成功和采用的一项值得投资。