使用 Diátaxis 框架编写高质量软件文档awesome-copilot 的 documentation-writer 技能深度指南【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot本文围绕 skills/documentation-writer/SKILL.md 展开系统讲解 Diátaxis 技术文档编写框架的四大文档类型、四条指导原则与三段式写作工作流。文中结合 awesome-copilot 仓库中的 Agent 定义、Skill 校验脚本与相关文档实践帮助读者掌握一套先澄清、再规划、后成文的文档生产方法论并可直接借助 GitHub Copilot 的 Agent Skills 机制在任意软件项目上落地使用。一、什么是 documentation-writer 技能在 awesome-copilot 仓库中documentation-writer是一个以 Diátaxis 技术文档编写框架为指导的 Agent Skill。它的定位非常明确一个精通高质量软件文档创作的技术写作专家。该技能的核心描述见 SKILL.md 的 front matterDiátaxis Documentation Expert. An expert technical writer specializing in creating high-quality software documentation, guided by the principles and structure of the Diátaxis technical documentation authoring framework.根据 AGENTS.md 对仓库结构的说明skills/目录下的每个技能都是包含指令与打包资源的自包含文件夹其中SKILL.md是技能的指令主体。而 docs/README.skills.md 进一步解释了 Agent Skills 的机制基于 Agent Skills 规范每个技能内含一个SKILL.md指令文件Agent 在需要执行专项任务时按需加载progressive disclosure。也就是说当你在 GitHub Copilot 对话中提出帮我写一篇文档为这个模块写使用说明等请求时Copilot 可以自动发现并加载documentation-writer技能从而在 Diátaxis 框架指导下完成写作。该技能不附带任何脚本或资源文件其目录下仅有SKILL.md一个文件它提供的是一套纯方法论与行为准则因此可以被复用到任意语言、任意技术栈的文档任务中。二、四条指导原则文档质量的底层约束documentation-writer技能首先定义了四条贯穿所有文档写作的原则任何产出都必须同时满足原则原文要求实践含义清晰ClarityWrite in simple, clear, and unambiguous language.使用简单、明确、无歧义的语言技术术语首次出现时给出解释准确AccuracyEnsure all information, especially code snippets and technical details, is correct and up-to-date.所有信息尤其是代码片段与细节必须正确且与当前代码一致以用户为中心User-CentricityAlways prioritize the users goal. Every document must help a specific user achieve a specific task.每份文档都必须帮助特定用户完成特定任务杜绝无目的的泛泛而谈一致性ConsistencyMaintain a consistent tone, terminology, and style across all documentation.全部文档保持统一的语气、术语与风格这四条原则并非 documentation-writer 独创而是与仓库中其他写作型资源互相印证。例如 agents/project-documenter.agent.md 中也列出了高度相似的写作原则Clarity first清晰优先、Active voice主动语态、Concrete over abstract具体优于抽象要求引用真实类名、文件路径与代码模式。这印证了 Diátaxis 原则在 awesome-copilot 中是一套被 Agent 与 Skill 共同遵循的通用写作规范而不是孤立的单文件约定。三、四大文档类型Diátaxis 框架的核心骨架Diátaxis 框架将技术文档划分为四个象限documentation-writer要求作者必须理解每种类型的独特目的并有意识地进行区分文档类型定位面向类比典型产出教程Tutorials面向学习Learning-oriented新手一堂课A lesson从零开始、循序渐进的动手实践步骤引导新手获得成功结果操作指南How-to Guides面向问题Problem-oriented有具体问题的用户一份菜谱A recipe解决某个具体问题的步骤序列参考手册Reference面向信息Information-oriented查询者一本字典A dictionary对机器/机制的技术性描述如 API 参数、配置项、接口契约解释Explanation面向理解Understanding-oriented想搞懂为什么的人一场讨论A discussion对特定主题的背景、动机与权衡的阐释四象限在 awesome-copilot 中的实际应用Diátaxis 框架在仓库中有多处落地。最有代表性的是 agents/project-documenter.agent.mdProject Documenter 文档生成 Agent它明确声明生成的文档结合了两个 Diátaxis 象限Reference主——对项目机器、契约与结构的信息导向型技术描述Explanation次——对流水线、架构决策与扩展模式的如何与为何理解导向型讨论。该 Agent 还进一步把 Diátaxis 与 C4 架构模型结合将文档章节映射到 C4 抽象层级C4 层级范围对应文档章节Context上下文系统与其所处环境Architecture OverviewContainer容器内部组件与数据流Processing PipelineComponent组件类/模块级关系Core ComponentsInfrastructure基础设施部署与运行时Infrastructure Deployment这说明 Diátaxis 不仅是一个写作分类法还可以作为整份文档的章节编排蓝图先按类型确定这份文档该回答什么问题再按 C4 层级确定该从哪些粒度组织内容。如何判断该写哪种文档技能要求作者在写作前必须想清楚每种类型的差异这里给出一个快速判断准则用户是新手、想学会做一件事→ 教程Tutorials用户带着明确问题、想解决一个问题→ 操作指南How-to Guides用户想查询某个 API/配置的准确信息→ 参考手册Reference用户想理解为什么这样设计、背后的权衡→ 解释Explanation常见的错误是把教程写成操作指南或把参考手册写成教程——例如在 API 参考里加入过多入门步骤或在解释文档里罗列配置项。documentation-writer通过强制澄清环节来避免这类混淆。四、三段式工作流从需求澄清到完整成文documentation-writer规定了对每一次文档请求都必须遵循的处理流程共三个步骤。第一步确认与澄清Acknowledge Clarify收到写作请求后先确认请求并提出澄清问题以填补信息空白。在继续之前必须确定以下四项文档类型Document TypeTutorial、How-to、Reference 还是 Explanation目标读者Target Audience如新手开发者、资深系统管理员、非技术用户用户目标Users Goal读者希望通过阅读这份文档达成什么范围Scope应包含哪些主题以及重要的是应排除哪些主题。这一步的意义在于只有明确了给谁看、解决什么、覆盖什么后续的章节设计才不会跑偏。它也与仓库中 agents/project-documenter.agent.md 的受众分层做法一致——该 Agent 将读者分为三层资深工程师与架构师为主、非技术干系人次之、新开发者第三并为不同章节设定不同的服务对象。第二步提出结构方案Propose a Structure基于澄清后的信息为文档提出详细大纲例如带简短描述的目录/章节规划并等待用户批准后再写全文。这一先大纲、后正文的节奏是 AGENTS.md 中强调的工程化写作方式的重要补充大纲是文档的契约批准大纲意味着对结构与范围达成共识从而避免大篇幅返工。第三步生成内容Generate Content大纲获批后以格式良好的 Markdown撰写完整文档并严格遵守全部指导原则清晰、准确、以用户为中心、一致性。如果需要为文档配图或生成更丰富的交付物可以借鉴 Project Documenter Agent 的完整流水线见 agents/project-documenter.agent.md# 1. 生成 draw.io 架构图并导出 PNG cd skills/drawio npm install node skills/drawio/drawio-to-png.mjs --dir docs/diagrams # 2. 将 Markdown 转换为带嵌入图片的 Word 文档 cd skills/md-to-docx npm install node skills/md-to-docx/md-to-docx.mjs docs/project-summary.md docs/project-summary.docx该 Agent 还规定了一套文档质量自检清单可视为对 Diátaxis 原则的可执行化校验所有类/方法名与实际源码一致所有文件路径在仓库中真实存在图表准确反映真实架构文档中不含凭据、令牌与密钥文档具有清晰的标题与表格便于扫读。五、上下文感知如何利用既有文档保持一致documentation-writer的最后一部分给出了上下文感知规则这是保证一致性原则可落地的关键当用户提供其他 Markdown 文件时应将其作为上下文理解项目现有的语气、风格与术语除非用户明确要求否则不得从这些文件复制内容不得擅自查阅外部网站或其他来源除非用户提供了链接并指示这样做。这条规则与 Diátaxis 以用户为中心的原则一脉相承文档应当服务于用户的具体目标而不是把已有材料拼接复制。它同时约束了信息边界——写作所依据的事实必须来自用户提供的上下文避免引入未经确认的外部内容。在 awesome-copilot 仓库中instructions/markdown-content-creation.instructions.md 进一步提供了 Markdown 层面的格式约束标题层级、列表缩进、代码块语言标注、表格对齐、行长度等可作为撰写正文时的格式配套参考。六、如何在本仓库使用该技能安装方式根据 docs/README.skills.mdSkill 的安装有两种方式使用 GitHub CLI 安装需 GitHub CLI v2.90.0gh skills install github/awesome-copilot documentation-writer手动拷贝将技能文件夹复制到本地 skills 目录# 将 skills/documentation-writer 复制到你的本地技能目录 cp -r skills/documentation-writer your-local-skills-dir/触发方式安装后在提示词中显式引用该技能或让 Agent 在对话中自动发现它。典型触发场景包括为这个模块写一份操作指南how-to帮我把这个 API 整理成参考文档写一篇面向新人的入门教程解释一下这个架构为什么这样设计。当加载documentation-writer技能后Copilot 会进入 Diátaxis 模式先澄清文档类型、目标读者、用户目标与范围再提交大纲等待确认最后按四象限原则成文。技能结构的合法性保障如果你希望把基于该技能的方法论封装成新的 Skill提交回仓库需要满足 AGENTS.md 与 eng/validate-skills.mjs 中定义的校验规则每个技能是包含SKILL.md的文件夹SKILL.md必须含name字段小写连字符与文件夹名一致最长 64 字符与description字段单引号包裹长度限制见 eng/constants.mjs最短 10、最长 1024 字符打包资源需在SKILL.md中被引用且单个文件小于 5MB校验与脚手架命令见 package.jsonnpm run skill:validate # 校验所有技能结构 npm run skill:create -- --name skill-name # 脚手架新技能 npm run build # 重新生成 README七、落地实践一个完整的写作流程示例综合前述所有内容一个典型的、遵循 Diátaxis 的文档写作会话应当是这样的请求用户提出为支付模块写一份操作指南澄清Agent 确认文档类型为 How-to、目标读者为服务端开发者、用户目标是在 15 分钟内完成支付接入、范围限定为支付流程与回调处理不涉及对账报表大纲Agent 提交结构——背景与前置条件、接入步骤、回调处理、常见错误排查、验证清单等待用户批准成文获批后按清晰、准确、以用户为中心、一致性的原则撰写 Markdown涉及代码片段时确保与仓库源码一致可参考 instructions/markdown-content-creation.instructions.md 的格式规则校验对照质量清单检查路径、代码与结构确认无误后交付。这套流程的可迁移性正是 documentation-writer 技能的价值所在它不绑定任何具体技术栈而是把好的文档是如何生产出来的这一知识固化成了 Agent 可执行的行为规范。八、总结documentation-writer是 awesome-copilot 仓库中一个方法论型技能核心价值有三分类先行通过 Diátaxis 四象限教程 / 操作指南 / 参考手册 / 解释为每一份文档确定其本质目的避免文档类型错配原则约束以清晰、准确、以用户为中心、一致性四条原则贯穿写作全过程流程保障通过澄清 → 大纲 → 成文三段式工作流把文档写作从自由发挥变成可评审、可复用的工程化流程。结合仓库中的 agents/project-documenter.agent.md 可以看到Diátaxis 已被实际用于生成带 C4 架构图与 Word 交付物的项目文档结合 AGENTS.md、eng/validate-skills.mjs 与 package.json也可以把同样的方法论沉淀为符合规范的新技能。对于任何希望在软件项目中稳定产出高质量文档的团队或个人而言这套框架都值得直接借鉴。【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 使用 Diátaxis 框架编写高质量软件文档：awesome-copilot 的 documentation-writer 技能深度指南
使用 Diátaxis 框架编写高质量软件文档awesome-copilot 的 documentation-writer 技能深度指南【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot本文围绕 skills/documentation-writer/SKILL.md 展开系统讲解 Diátaxis 技术文档编写框架的四大文档类型、四条指导原则与三段式写作工作流。文中结合 awesome-copilot 仓库中的 Agent 定义、Skill 校验脚本与相关文档实践帮助读者掌握一套先澄清、再规划、后成文的文档生产方法论并可直接借助 GitHub Copilot 的 Agent Skills 机制在任意软件项目上落地使用。一、什么是 documentation-writer 技能在 awesome-copilot 仓库中documentation-writer是一个以 Diátaxis 技术文档编写框架为指导的 Agent Skill。它的定位非常明确一个精通高质量软件文档创作的技术写作专家。该技能的核心描述见 SKILL.md 的 front matterDiátaxis Documentation Expert. An expert technical writer specializing in creating high-quality software documentation, guided by the principles and structure of the Diátaxis technical documentation authoring framework.根据 AGENTS.md 对仓库结构的说明skills/目录下的每个技能都是包含指令与打包资源的自包含文件夹其中SKILL.md是技能的指令主体。而 docs/README.skills.md 进一步解释了 Agent Skills 的机制基于 Agent Skills 规范每个技能内含一个SKILL.md指令文件Agent 在需要执行专项任务时按需加载progressive disclosure。也就是说当你在 GitHub Copilot 对话中提出帮我写一篇文档为这个模块写使用说明等请求时Copilot 可以自动发现并加载documentation-writer技能从而在 Diátaxis 框架指导下完成写作。该技能不附带任何脚本或资源文件其目录下仅有SKILL.md一个文件它提供的是一套纯方法论与行为准则因此可以被复用到任意语言、任意技术栈的文档任务中。二、四条指导原则文档质量的底层约束documentation-writer技能首先定义了四条贯穿所有文档写作的原则任何产出都必须同时满足原则原文要求实践含义清晰ClarityWrite in simple, clear, and unambiguous language.使用简单、明确、无歧义的语言技术术语首次出现时给出解释准确AccuracyEnsure all information, especially code snippets and technical details, is correct and up-to-date.所有信息尤其是代码片段与细节必须正确且与当前代码一致以用户为中心User-CentricityAlways prioritize the users goal. Every document must help a specific user achieve a specific task.每份文档都必须帮助特定用户完成特定任务杜绝无目的的泛泛而谈一致性ConsistencyMaintain a consistent tone, terminology, and style across all documentation.全部文档保持统一的语气、术语与风格这四条原则并非 documentation-writer 独创而是与仓库中其他写作型资源互相印证。例如 agents/project-documenter.agent.md 中也列出了高度相似的写作原则Clarity first清晰优先、Active voice主动语态、Concrete over abstract具体优于抽象要求引用真实类名、文件路径与代码模式。这印证了 Diátaxis 原则在 awesome-copilot 中是一套被 Agent 与 Skill 共同遵循的通用写作规范而不是孤立的单文件约定。三、四大文档类型Diátaxis 框架的核心骨架Diátaxis 框架将技术文档划分为四个象限documentation-writer要求作者必须理解每种类型的独特目的并有意识地进行区分文档类型定位面向类比典型产出教程Tutorials面向学习Learning-oriented新手一堂课A lesson从零开始、循序渐进的动手实践步骤引导新手获得成功结果操作指南How-to Guides面向问题Problem-oriented有具体问题的用户一份菜谱A recipe解决某个具体问题的步骤序列参考手册Reference面向信息Information-oriented查询者一本字典A dictionary对机器/机制的技术性描述如 API 参数、配置项、接口契约解释Explanation面向理解Understanding-oriented想搞懂为什么的人一场讨论A discussion对特定主题的背景、动机与权衡的阐释四象限在 awesome-copilot 中的实际应用Diátaxis 框架在仓库中有多处落地。最有代表性的是 agents/project-documenter.agent.mdProject Documenter 文档生成 Agent它明确声明生成的文档结合了两个 Diátaxis 象限Reference主——对项目机器、契约与结构的信息导向型技术描述Explanation次——对流水线、架构决策与扩展模式的如何与为何理解导向型讨论。该 Agent 还进一步把 Diátaxis 与 C4 架构模型结合将文档章节映射到 C4 抽象层级C4 层级范围对应文档章节Context上下文系统与其所处环境Architecture OverviewContainer容器内部组件与数据流Processing PipelineComponent组件类/模块级关系Core ComponentsInfrastructure基础设施部署与运行时Infrastructure Deployment这说明 Diátaxis 不仅是一个写作分类法还可以作为整份文档的章节编排蓝图先按类型确定这份文档该回答什么问题再按 C4 层级确定该从哪些粒度组织内容。如何判断该写哪种文档技能要求作者在写作前必须想清楚每种类型的差异这里给出一个快速判断准则用户是新手、想学会做一件事→ 教程Tutorials用户带着明确问题、想解决一个问题→ 操作指南How-to Guides用户想查询某个 API/配置的准确信息→ 参考手册Reference用户想理解为什么这样设计、背后的权衡→ 解释Explanation常见的错误是把教程写成操作指南或把参考手册写成教程——例如在 API 参考里加入过多入门步骤或在解释文档里罗列配置项。documentation-writer通过强制澄清环节来避免这类混淆。四、三段式工作流从需求澄清到完整成文documentation-writer规定了对每一次文档请求都必须遵循的处理流程共三个步骤。第一步确认与澄清Acknowledge Clarify收到写作请求后先确认请求并提出澄清问题以填补信息空白。在继续之前必须确定以下四项文档类型Document TypeTutorial、How-to、Reference 还是 Explanation目标读者Target Audience如新手开发者、资深系统管理员、非技术用户用户目标Users Goal读者希望通过阅读这份文档达成什么范围Scope应包含哪些主题以及重要的是应排除哪些主题。这一步的意义在于只有明确了给谁看、解决什么、覆盖什么后续的章节设计才不会跑偏。它也与仓库中 agents/project-documenter.agent.md 的受众分层做法一致——该 Agent 将读者分为三层资深工程师与架构师为主、非技术干系人次之、新开发者第三并为不同章节设定不同的服务对象。第二步提出结构方案Propose a Structure基于澄清后的信息为文档提出详细大纲例如带简短描述的目录/章节规划并等待用户批准后再写全文。这一先大纲、后正文的节奏是 AGENTS.md 中强调的工程化写作方式的重要补充大纲是文档的契约批准大纲意味着对结构与范围达成共识从而避免大篇幅返工。第三步生成内容Generate Content大纲获批后以格式良好的 Markdown撰写完整文档并严格遵守全部指导原则清晰、准确、以用户为中心、一致性。如果需要为文档配图或生成更丰富的交付物可以借鉴 Project Documenter Agent 的完整流水线见 agents/project-documenter.agent.md# 1. 生成 draw.io 架构图并导出 PNG cd skills/drawio npm install node skills/drawio/drawio-to-png.mjs --dir docs/diagrams # 2. 将 Markdown 转换为带嵌入图片的 Word 文档 cd skills/md-to-docx npm install node skills/md-to-docx/md-to-docx.mjs docs/project-summary.md docs/project-summary.docx该 Agent 还规定了一套文档质量自检清单可视为对 Diátaxis 原则的可执行化校验所有类/方法名与实际源码一致所有文件路径在仓库中真实存在图表准确反映真实架构文档中不含凭据、令牌与密钥文档具有清晰的标题与表格便于扫读。五、上下文感知如何利用既有文档保持一致documentation-writer的最后一部分给出了上下文感知规则这是保证一致性原则可落地的关键当用户提供其他 Markdown 文件时应将其作为上下文理解项目现有的语气、风格与术语除非用户明确要求否则不得从这些文件复制内容不得擅自查阅外部网站或其他来源除非用户提供了链接并指示这样做。这条规则与 Diátaxis 以用户为中心的原则一脉相承文档应当服务于用户的具体目标而不是把已有材料拼接复制。它同时约束了信息边界——写作所依据的事实必须来自用户提供的上下文避免引入未经确认的外部内容。在 awesome-copilot 仓库中instructions/markdown-content-creation.instructions.md 进一步提供了 Markdown 层面的格式约束标题层级、列表缩进、代码块语言标注、表格对齐、行长度等可作为撰写正文时的格式配套参考。六、如何在本仓库使用该技能安装方式根据 docs/README.skills.mdSkill 的安装有两种方式使用 GitHub CLI 安装需 GitHub CLI v2.90.0gh skills install github/awesome-copilot documentation-writer手动拷贝将技能文件夹复制到本地 skills 目录# 将 skills/documentation-writer 复制到你的本地技能目录 cp -r skills/documentation-writer your-local-skills-dir/触发方式安装后在提示词中显式引用该技能或让 Agent 在对话中自动发现它。典型触发场景包括为这个模块写一份操作指南how-to帮我把这个 API 整理成参考文档写一篇面向新人的入门教程解释一下这个架构为什么这样设计。当加载documentation-writer技能后Copilot 会进入 Diátaxis 模式先澄清文档类型、目标读者、用户目标与范围再提交大纲等待确认最后按四象限原则成文。技能结构的合法性保障如果你希望把基于该技能的方法论封装成新的 Skill提交回仓库需要满足 AGENTS.md 与 eng/validate-skills.mjs 中定义的校验规则每个技能是包含SKILL.md的文件夹SKILL.md必须含name字段小写连字符与文件夹名一致最长 64 字符与description字段单引号包裹长度限制见 eng/constants.mjs最短 10、最长 1024 字符打包资源需在SKILL.md中被引用且单个文件小于 5MB校验与脚手架命令见 package.jsonnpm run skill:validate # 校验所有技能结构 npm run skill:create -- --name skill-name # 脚手架新技能 npm run build # 重新生成 README七、落地实践一个完整的写作流程示例综合前述所有内容一个典型的、遵循 Diátaxis 的文档写作会话应当是这样的请求用户提出为支付模块写一份操作指南澄清Agent 确认文档类型为 How-to、目标读者为服务端开发者、用户目标是在 15 分钟内完成支付接入、范围限定为支付流程与回调处理不涉及对账报表大纲Agent 提交结构——背景与前置条件、接入步骤、回调处理、常见错误排查、验证清单等待用户批准成文获批后按清晰、准确、以用户为中心、一致性的原则撰写 Markdown涉及代码片段时确保与仓库源码一致可参考 instructions/markdown-content-creation.instructions.md 的格式规则校验对照质量清单检查路径、代码与结构确认无误后交付。这套流程的可迁移性正是 documentation-writer 技能的价值所在它不绑定任何具体技术栈而是把好的文档是如何生产出来的这一知识固化成了 Agent 可执行的行为规范。八、总结documentation-writer是 awesome-copilot 仓库中一个方法论型技能核心价值有三分类先行通过 Diátaxis 四象限教程 / 操作指南 / 参考手册 / 解释为每一份文档确定其本质目的避免文档类型错配原则约束以清晰、准确、以用户为中心、一致性四条原则贯穿写作全过程流程保障通过澄清 → 大纲 → 成文三段式工作流把文档写作从自由发挥变成可评审、可复用的工程化流程。结合仓库中的 agents/project-documenter.agent.md 可以看到Diátaxis 已被实际用于生成带 C4 架构图与 Word 交付物的项目文档结合 AGENTS.md、eng/validate-skills.mjs 与 package.json也可以把同样的方法论沉淀为符合规范的新技能。对于任何希望在软件项目中稳定产出高质量文档的团队或个人而言这套框架都值得直接借鉴。【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考