Diátaxis 方法

在介绍这个skill之前，需要介绍一个系统性文档编写的方法，也就是 Diátaxis 方法，为什么会提到这个方法，因为今天介绍docs写作使用了包含这个方法的skill，我们看看skill的描述，如下

You are an expert technical writer specializing in creating high-quality software documentation. Your work is strictly guided by the principles and structure of the Diátaxis Framework (https://diataxis.fr/).

Diátaxis 规定了内容、架构和形式的方法，这些方法源自系统性地理解文档用户的需求。它指出了四种不同的需求，以及四种对应的文档形式——教程、操作指南、技术参考和解释。它将这些需求置于系统性关系中，并提出文档本身应围绕这些需求的结构进行组织。

它解决了与文档内容（写什么）、风格（如何编写）和架构（如何组织文档）的根本性问题，换句话说，使用这个skill，word工作将完全被替代

演示

首先安装这个skill

npx skills add https://github.com/github/awesome-copilot --skill documentation-writernpx skills add https://github.com/anthropics/skills --skill docx

首先我们查看desription描述，方便我们熟练调用这个skill

Diátaxis Documentation Expert. An expert technical writer specializing in creating high-quality software documentation, guided by the principles andstructureof the Diátaxis technical documentation authoring framework

然后登入claude

# claude  ▐▛███▜▌   Claude Code v2.1.83▝▜█████▛▘  Sonnet 4.6 · Claude Pro  ▘▘ ▝▝    ~/examples-docs

下面给出提示词，让其命中documentation-writer的description

❯ 请你深度分析 librtpi 的仓库，理解其原理和使用办法，为我提供一个documentation, 格式是docs。● Skill(documentation-writer)  ⎿  Successfully loaded skill● Skill(docx)  ⎿  Successfully loaded skill

可以看到skill成功命中，接下来就是等待其产出了

documentation-writer会有一个需求确认过程，我们看看他的需求确认信息

● 需求确认  在开始之前，我需要确认以下几点：  文档类型： 你的请求涉及多个 Diátaxis 象限——"理解原理"属于 Explanation（解释），而"使用办法"属于 How-to Guide（操作指南） 和 Reference（参考）。我计划创建一套结构化的文档覆盖这些需求。  目标受众：  - 是对实时系统有一定了解的中高级开发者？  - 还是对实时系统概念较陌生的新手？  使用目标：  - 主要用于学习入门（Tutorial）？  - 还是作为实际项目开发的参考手册（How-to + Reference）？  文档范围：  - 只需要英文文档，还是中英文都要？  - 是否需要包含 API 索引、FAQ、故障排除等补充内容？  请确认以上信息，或者如果你没有特殊要求，我可以按以下推荐方案直接生成：  推荐方案：  ┌────────────────────────┬──────────────┬──────────────────────────────┐  │          文档          │     类型     │             内容             │  ├────────────────────────┼──────────────┼──────────────────────────────┤  │ librtpi-guide.docs       │ How-to Guide │ 快速上手、使用示例、常见任务 │  ├────────────────────────┼──────────────┼──────────────────────────────┤  │ librtpi-reference.docs   │ Reference    │ 完整 API 参考、构建配置      │  ├────────────────────────┼──────────────┼──────────────────────────────┤  │ librtpi-explanation.docs │ Explanation  │ 原理、设计决策、技术细节     │  └────────────────────────┴──────────────┴──────────────────────────────┘  请确认或调整，我将据此生成文档。✻ Brewed for3m 48s

根据需求我们回答如下

❯ 目标受众：实时系统有一定了解的中高级开发者  使用目标：实际项目开发的参考手册  文档范围：中文文档，包含API 索引、FAQ、故障排除等补充内容

再次确认需求

● 明白了。我将为 librtpi 创建一套完整的中文技术文档，格式为 Word (.docx)。  提案：文档结构  基于 Diátaxis 框架和你的需求（目标受众：实时系统中高级开发者；用途：项目开发参考手册），我计划创建以下三份文档：  ┌──────────────────────────┬──────────────┬───────────────────────────────────────────────────────────┐  │           文档           │     类型     │                         主要内容                          │  ├──────────────────────────┼──────────────┼───────────────────────────────────────────────────────────┤  │ librtpi-guide.docx       │ How-to Guide │ 安装构建、快速入门、典型使用模式、迁移指南                │  ├──────────────────────────┼──────────────┼───────────────────────────────────────────────────────────┤  │ librtpi-reference.docx   │ Reference    │ 完整 API 索引、宏定义说明、构建选项、测试说明             │  ├──────────────────────────┼──────────────┼───────────────────────────────────────────────────────────┤  │ librtpi-explanation.docx │ Explanation  │ 优先级继承原理、Requeue-PI 机制、设计决策、FAQ 与故障排除 │  └──────────────────────────┴──────────────┴───────────────────────────────────────────────────────────┘  文档语言： 中文（正文）+ 英文 API 名称（保留代码风格）  请确认：1. 是否同意上述结构？2. 三份文档是否分别生成独立的 .docx 文件？3. 是否有特定的品牌颜色/样式要求？

这里我想要一份docs，我准确提出我的需求

❯ 1. 我需要都在一份docx文件中2. 请大胆设计，但要求格式整洁

claude正确的理解了我的需求

● 明白了！我将创建一份结构完整、设计整洁的综合文档，涵盖所有 Diátaxis 象限。

大概不到10分钟，文档生成完毕了，如下

● 文档已成功生成！  生成结果  文件： ~/claude/librtpi_技术参考文档.docx (48KB)  文档结构概览  ┌────────────────────┬───────┬──────────────────────────────────────────────────────────┐  │        部分        │ 章节  │                           内容                           │  ├────────────────────┼───────┼──────────────────────────────────────────────────────────┤  │ 封面               │ -     │ 标题、副标题、版本信息                                   │  ├────────────────────┼───────┼──────────────────────────────────────────────────────────┤  │ 目录               │ -     │ 三大部分索引                                             │  ├────────────────────┼───────┼──────────────────────────────────────────────────────────┤  │ 第一部分：操作指南 │ 1-5   │ 概述、安装构建、快速入门、典型使用模式、迁移指南         │  ├────────────────────┼───────┼──────────────────────────────────────────────────────────┤  │ 第二部分：参考手册 │ 6-9   │ C API、C++ API、构建选项、测试说明                       │  ├────────────────────┼───────┼──────────────────────────────────────────────────────────┤  │ 第三部分：原理解析 │ 10-13 │ 优先级继承原理、Requeue-PI 机制、设计决策、FAQ与故障排除 │  ├────────────────────┼───────┼──────────────────────────────────────────────────────────┤  │ 附录               │ A     │ 数据结构定义                                             │  └────────────────────┴───────┴──────────────────────────────────────────────────────────┘  设计特点  - A4 页面，适合技术文档阅读  - 配色方案：深蓝色主色调 + 橙色强调色  - 代码块：灰色背景，便于区分  - 表格：交替行颜色 + 表头高亮  - 提示框：信息/警告/提示三种类型  - 层次结构：3级标题体系✻ Worked for7m 22s