writing-documentation-with-diataxis by sammcj/agentic-coding
npx skills add https://github.com/sammcj/agentic-coding --skill writing-documentation-with-diataxis你帮助用户使用 Diataxis 框架创建和改进技术文档,该框架根据用户需求识别出四种不同的文档类型。
Diataxis 是一个用于创建使用体验良好的文档的框架——这种文档具有流畅性、能预见需求,并且符合人类实际与技艺互动的方式。
重要提示:Diataxis 是一种方法,而非模板。不要为了凑齐教程/操作指南/参考/说明而创建空的部分。创建服务于实际用户需求的内容,应用这些原则,并让结构自然形成。
核心见解:文档服务于特定技能领域的实践者。他们的需求根据两个维度而变化:
这正好产生了四种文档类型:
为什么正好是四种:这些不是任意的分类。这两个维度正好划分出四个象限——不可能有三个或五个。这是文档必须覆盖的完整领域。
当不确定需要哪种文档类型时,问两个问题:
1. 内容是告知 ACTION 还是 COGNITION?
2. 它是服务于技能的 ACQUISITION 还是 APPLICATION?
然后应用:
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| 内容类型 | 用户活动 | 文档类型 |
|---|
| 行动 | 习得 | 教程 |
| 行动 | 应用 | 操作指南 |
| 认知 | 应用 | 参考 |
| 认知 | 习得 | 说明 |
问自己:
应用上面的两个问题来确定哪种文档类型能满足这个需求。
对于教程(通过实践学习):
对于操作指南(为实现目标而工作):
对于参考(工作中的事实):
对于说明(理解概念):
教程:"我们将创建..." "首先,做 X。现在,做 Y。" "注意..." "你已经构建了..."
操作指南:"本指南向你展示如何..." "如果你想要 X,做 Y" "要实现 W,做 Z"
参考:"X 可作为 Y 使用" "子命令有:A, B, C" "你必须使用 X。切勿使用 Y。"
说明:"X 的原因是..." "W 比 Z 更好,因为..." "有些人更喜欢 W。这可能有效,但是..."
检查你的内容:
如果内容服务于多种需求,将其拆分并在文档之间建立链接。
使用这个迭代工作流程:
1. 选择一部分 - 任何页面、章节或段落
2. 用这些问题挑战它:
3. 如果不确定类型,使用指南针
4. 确定一个现在就能帮助改进的地方
5. 根据 Diataxis 原则进行改进
6. 对另一部分重复此过程
不要试图一次性重构所有内容。结构是通过改进各个部分而自然形成的。
流畅性至关重要:文档应该与用户顺畅地同步,预见他们的下一个需求。特别是对于操作指南,思考:他们必须记住什么?他们什么时候可以解决这些想法?他们接下来会需要什么?
边界具有保护性:保持文档类型分离。最常见的错误是将教程(学习)与操作指南(工作)混在一起。
结构跟随内容:不要创建空的部分。编写服务于真实需求的内容,应用 Diataxis 原则,并让结构自然形成。
一次满足一个需求:每个部分服务于一个用户需求。如果用户需要多个东西,创建多个部分并在它们之间建立链接。
好的文档感觉良好:除了准确性之外,文档还应该预见需求、具有流畅性,并符合人类的工作方式。
教程/操作指南混淆 - 教程用于学习(研究),操作指南用于工作。你混淆了它们的迹象:
在教程中过度解释 - 相信学习是通过实践发生的。给予最少的解释,并将详细说明链接到其他地方。
试图教学的操作指南 - 假设用户有足够能力。不要解释基础知识。
进行指导的参考 - 参考是描述性的,它不告诉你该做什么。
面向行动的文档中的说明 - 将其移到说明文档并链接到它。
| 方面 | 教程 | 操作指南 | 参考 | 说明 |
|---|---|---|---|---|
| 回答 | "你能教我吗?" | "我如何...?" | "什么是...?" | "为什么...?" |
| 用户状态 | 通过实践学习 | 处理任务 | 工作中,需要事实 | 为理解而学习 |
| 内容 | 行动步骤 | 行动步骤 | 信息 | 信息 |
| 形式 | 一堂课 | 指示 | 描述 | 讨论 |
| 责任 | 在教师身上 | 在用户身上 | 中性 | 共享 |
| 语气 | 支持性,引导性 | 直接,有条件性 | 简洁,事实性 | 发散性,上下文性 |
如需更详细的指导,请参阅:
应用 Diataxis 时:
每周安装量
230
代码仓库
GitHub 星标数
112
首次出现
2026年1月27日
安全审计
安装于
opencode221
codex220
gemini-cli218
github-copilot217
cursor208
kimi-cli208
You help users create and improve technical documentation using the Diataxis framework, which identifies four distinct documentation types based on user needs.
Diataxis is a framework for creating documentation that feels good to use - documentation that has flow, anticipates needs, and fits how humans actually interact with a craft.
Important : Diataxis is an approach, not a template. Don't create empty sections for tutorials/how-to/reference/explanation just to have them. Create content that serves actual user needs, apply these principles, and let structure emerge organically.
Core insight : Documentation serves practitioners in a domain of skill. What they need changes based on two dimensions:
These create exactly four documentation types:
Why exactly four : These aren't arbitrary categories. The two dimensions create exactly four quarters - there cannot be three or five. This is the complete territory of what documentation must cover.
When uncertain which documentation type is needed, ask two questions:
1. Does the content inform ACTION or COGNITION?
2. Does it serve ACQUISITION or APPLICATION of skill?
Then apply:
| Content Type | User Activity | Documentation Type |
|---|---|---|
| Action | Acquisition | Tutorial |
| Action | Application | How-to Guide |
| Cognition | Application | Reference |
| Cognition | Acquisition | Explanation |
Ask yourself:
Apply the two questions above to determine which documentation type serves this need.
For Tutorials (learning by doing):
For How-to Guides (working to achieve goals):
For Reference (facts while working):
For Explanation (understanding concepts):
Tutorials : "We will create..." "First, do X. Now, do Y." "Notice that..." "You have built..."
How-to Guides : "This guide shows you how to..." "If you want X, do Y" "To achieve W, do Z"
Reference : "X is available as Y" "Sub-commands are: A, B, C" "You must use X. Never Y."
Explanation : "The reason for X is..." "W is better than Z, because..." "Some prefer W. This can be effective, but..."
Review your content:
If content serves multiple needs, split it and link between documents.
Use this iterative workflow:
1. Choose a piece - Any page, section, or paragraph
2. Challenge it with these questions:
3. Use the compass if the type is unclear
4. Identify one improvement that would help right now
5. Make that improvement according to Diataxis principles
6. Repeat with another piece
Don't try to restructure everything at once. Structure emerges from improving individual pieces.
Flow is paramount : Documentation should move smoothly with the user, anticipating their next need. For how-to guides especially, think: What must they hold in their mind? When can they resolve those thoughts? What will they reach for next?
Boundaries are protective : Keep documentation types separate. The most common mistake is mixing tutorials (learning) with how-to guides (working).
Structure follows content : Don't create empty sections. Write content that serves real needs, apply Diataxis principles, and let structure emerge organically.
One need at a time : Each piece serves one user need. If users need multiple things, create multiple pieces and link between them.
Good documentation feels good : Beyond accuracy, documentation should anticipate needs, have flow, and fit how humans work.
Tutorial/How-to conflation - Tutorials are for learning (study), how-to guides are for working. Signs you've mixed them:
Over-explaining in tutorials - Trust that learning happens through doing. Give minimal explanation and link to detailed explanation elsewhere.
How-to guides that teach - Assume competence. Don't explain basics.
Reference that instructs - Reference describes, it doesn't tell you what to do.
Explanation in action-oriented docs - Move it to explanation docs and link to it.
| Aspect | Tutorials | How-to Guides | Reference | Explanation |
|---|---|---|---|---|
| Answers | "Can you teach me?" | "How do I...?" | "What is...?" | "Why...?" |
| User is | Learning by doing | Working on task | Working, needs facts | Studying to understand |
| Content | Action steps | Action steps | Information | Information |
| Form | A lesson | Directions | Description | Discussion |
| Responsibility | On the teacher | On the user | Neutral |
For more detailed guidance, refer to:
When applying Diataxis:
Weekly Installs
230
Repository
GitHub Stars
112
First Seen
Jan 27, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
opencode221
codex220
gemini-cli218
github-copilot217
cursor208
kimi-cli208
新闻稿撰写工具:使用 inference.sh CLI 进行事实核查与专业新闻稿创作
7,400 周安装
ASP.NET 最小 API OpenAPI 文档生成器 - 构建强类型、文档完善的 Web API
7,600 周安装
WorkIQ Copilot:AI助手连接Microsoft 365,智能查询邮件、会议、文档和Teams消息
7,600 周安装
Power BI报表设计专家咨询 | 可视化设计、用户体验优化、数据驱动决策指南
7,600 周安装
传统电路模拟图技能:创建复古面包板布局与交互式电路示意图
7,700 周安装
AI就绪规范更新指南 - 结构化文档模板与最佳实践
7,600 周安装
VS Code 记忆指令管理工具:remember - 智能分类经验教训,构建领域知识库
7,700 周安装
| Shared |
| Tone | Supportive, guiding | Direct, conditional | Austere, factual | Discursive, contextual |