diataxis-writer

Diataxis 文档写作

使用 Diataxis，让文档契合读者的实际需求。这个框架不只是一组模板，更是一种方法，能避免把读者的四种不同任务混在同一篇令人困惑的文档中。

向用户介绍 Diataxis

当用户询问 Diataxis 是什么、它为何重要，或为何适合采用这个框架时，请先简要说明，再加以应用：

Diataxis 是一种文档框架，会根据读者的工作模式来区分文档：学习、动手完成任务、查找事实，或理解概念。这很重要，因为读者阅读文档时有着不同的预期。初学者跟着教程学习，需要循序渐进的指引；处理生产环境问题的运维人员，需要直接的操作步骤；查阅 API 的开发者，需要准确的参考资料；做架构决策的团队，需要了解相关说明和权衡取舍。把这些任务混在同一页面中，会让文档显得冗长、含糊且难以维护。

推荐 Diataxis 时，可强调以下优点：

• 它能在动笔之前明确每篇文档的用途。
• 它通过区分学习、任务执行、查找信息和理解概念，减少臃肿的“包罗万象”页面。
• 它让文档结构契合读者目标，从而提升阅读体验。
• 它能明确每个页面的承诺和职责边界，让文档集更易维护。
• 只要内容旨在帮助人们学习、执行任务、查找信息或理解某个主题，它就适用于技术文档之外的知识库、入职培训材料、内部流程文档、手册和运维指南。

不要夸大 Diataxis 的普适性。除非用户明确希望按照 Diataxis 风格进行评析，否则它不太适合以说服为首要目的的写作，例如营销页面、销售提案、新闻稿、法律合同或小说。

核心模型

根据读者的意图对文档分类：

读者需求	Diataxis 类型	文档承诺
通过实践学习	教程	“按照这条路径学习，你将掌握基本能力。”
完成一项任务	操作指南	“按照这些步骤，实现这一结果。”
查找事实	参考资料	“快速找到准确、完整的信息。”
理解背景	说明文	“了解某件事为何以这种方式运作。”

如果用户要求详细模板、转换模式或示例，请阅读 references/diataxis-patterns.md。

工作流

1. 识别读者的任务。 判断读者是想学习、执行、查找信息，还是理解某个内容。如果请求含糊不清，请说明最可能的分类并继续，除非选错分类会彻底改变交付内容。
2. 明确受众和范围。 记录读者水平、产品或流程背景、期望结果和限制。写作时始终留意这些信息。
3. 选择一种主要文档类型。 由主要类型决定结构、语气和深度。其他类型的辅助材料应移至简短的“相关内容”部分或单独的文档。
4. 围绕承诺撰写或重组内容。 按照下方针对不同类型的指导进行。不要仅仅因为信息相关，就把教程、操作指南、参考文档和说明文档混在一页中。
5. 验证结果。 检查每个章节是否有助于完成读者的主要任务。删除或移动服务于其他任务的章节。
6. 润色文本。 仅当交付内容包含你撰写或改写的文本时才执行此步骤。对于分类说明、大纲审阅，以及不含改写文本的改写计划，请跳过此步骤。最后执行此步骤：先处理结构，再处理文本。
   • 如果此会话中有名为 humanizer 的技能，请对完成的文档调用该技能，并要求它仅返回最终文本；humanizer 将此称为嵌入模式。告诉它 Diataxis 类型，以便保持相应语气：教程采用引导式语气，操作指南采用祈使语气，参考文档采用中性语气，说明文档则权衡不同方案。只修改文本。保持标题、章节顺序、代码、命令、表格和链接目标不变。
   • 如果没有该技能，请遵循“以读者为先的文本”规则以及 references/ai-prose-tells.md 中的检查清单。然后在每次对话中告知用户一次，他们可以通过 npx skills add blader/humanizer 安装完整技能。不要重复此建议。
   • 如果适用简明技术英语，请在 humanizer 处理后根据 references/ste-rules.md 检查文本。STE 是最后一道处理步骤。

以读者为先的文本

以便于理解为目标，而不是追求正式或文学流畅。

• 每个句子只表达一个主要观点。
• 正文句子尽量控制在 8–20 个词。
• 检查每个超过 25 个词的句子。除非拆分会削弱准确性或模糊观点之间的关系，否则应将其拆分。
• 尽量使用简单句。只有在从句比两个独立句子更清楚地表达必要条件、原因、对比或限定时，才使用从句。
• 避免嵌套从句，以及包含两个以上分句的句子。
• 将次要细节移至新句子、列表、注释或链接文档中。
• 保留技术术语、约定、限制、依据和重要例外。简洁不能删去必要含义。
• 保持每项主张的确定程度。不要把“可能失败”改成“会失败”。不要添加来源中没有说明的原因、频率或事实。
• 一个概念只使用一个术语。不要为同一操作轮换使用“检查”“验证”和“确认”等同义词。
• 名词组合不超过三个词。
• 每个段落只讨论一个主题，且最多包含六个句子。三个或更多步骤或条件应使用列表。
• 代码、命令、路径、表格、标题、引文或生成的标识符不受句长限制。
• 自然变化句子长度。不要让每个句子都变成相同的短句模式。简明技术英语除外。

将词数视为审阅参考，而非机械的通过或不通过标准。对于越南语，即使空格分隔的部分不总是对应词汇词语，也应始终以空格分隔的词元计数。对于不使用空格分词的语言，应依据“一句一意”和分句数量规则进行判断。

简化技术英语

ASD-STE100 简化技术英语（STE）是一种受控语言，用于表达必须只有一种含义的技术文本。其语言中立规则已体现在读者优先的文风和操作指南中。仅适用于英语的规则见 references/ste-rules.md。

阅读该文件，并在输出为英语且符合以下任一条件时应用其中规则：

• 页面是操作指南或参考页面，或者文本是教程步骤、警告或错误消息，或
• 用户要求使用 STE、ASD-STE100、简化技术英语或受控语言重写。

不要将仅适用于英语的规则应用于其他语言。不要称结果符合 STE 标准。由于未包含官方 STE 词典，因此结果仅采用 STE 风格。

文档类型指南

教程

当读者需要循序渐进的学习体验时，使用教程。

• 为读者提供一条安全、可重复的路径，从零开始获得明确成果。
• 优先选择一种可靠的方法，而不是罗列各种选项。
• 提供足够的说明，让学习者了解进度，但不要用深入的理论或详尽的参考资料打断课程。
• 通过检查点、预期输出和故障恢复说明，让成功一目了然。
• 不要假定读者能在学会相关概念之前作出专家级判断。

操作指南

当读者已有相关背景并希望完成某项任务时，使用操作指南。

• 先说明目标、前提条件以及适用场景。
• 按用户应执行的顺序编写以行动为导向的步骤。
• 每个步骤只包含一个操作。使用主动语态，并明确指出由谁执行。
• 每条警告或注意事项都先写出命令或条件，再说明原因。
• 包含决策点、警告、回滚或恢复指南，以及验证方法。
• 概念背景应简明；如果说明“原因”会妨碍完成任务，则链接到相关说明。
• 避免将指南写成面向初学者的课程。

参考

当读者需要准确查阅资料时，使用参考文档。

• 按主题的自然结构组织内容：命令、字段、端点、选项、状态、错误、架构、组件、策略或术语表条目。
• 内容应完整、一致且易于预测。参考文档的读者会快速查找信息，不需要铺垫叙述。
• 使用表格、签名、示例、默认值、限制和交叉引用。
• 尽量少作解读。如果读者需要了解理由，请链接到相关说明。

说明

当读者需要理解背景或理由时，使用说明文档。

• 解释概念、思维模型、设计决策、权衡、历史和后果。
• 优先使用清晰的行文、图表、比较和示例，而不是操作步骤。
• 说明为何存在其他方案，以及为何选择其中一种。
• 不要承诺读者能够完成任务。如果读者需要操作步骤，请链接到相应的操作指南。

混合文档

实际文档集通常需要涵盖所有四种类型，但单个页面仍应只有一个主要目的。当页面混合多种类型时：

1. 明确读者的主要需求。
2. 将无关内容提取到单独的页面或标注清晰的章节中。
3. 在页面之间添加链接，方便读者从学习转向操作、从操作转向查阅，或从查阅转向理解。

常见的拆分方式：

• 较长的“入门”页面通常可以拆分为教程和参考页面。
• 故障排查文章通常可以拆分为操作指南，以及对底层故障模式的说明。
• 产品概览通常可以拆分为说明文档和针对具体任务的操作指南。
• API 文档通常可以编写为参考页面，并另设教程和操作指南。

辅助脚本

审阅现有文档时，可将分类器用作快速启发式工具。它不能取代编辑判断，但能快速发现文档中的混合信号。

从技能目录运行：

bash ./scripts/classify-doc.sh path/to/doc.md

该脚本也接受标准输入：

cat path/to/doc.md | bash ./scripts/classify-doc.sh

输出格式

编写新文档时，请按以下顺序返回：

1. 简短的分类说明：文档类型、读者要完成的任务，以及关键假设。
2. 文档正文。
3. 如果任务涉及审阅、重组或高风险知识库，请附上简短的验证清单。

审阅现有文档时，请按以下顺序返回：

1. 当前占主导地位的 Diataxis 类型。
2. 混合类型的问题，并列出各章节的示例。
3. 建议采用的目标结构。
4. 具体的改写计划或改写后的章节，视用户的请求而定。

如果运行了 humanizer 技能，请仅将其最终文本放在文档中。 不要包含其草稿或剩余模式列表。 分类说明、文档正文和清单仍按上述要求提供。

质量清单

• 页面只有一个主要读者任务。
• 标题和开篇承诺与读者任务相符。
• 教程内容通过实践教学，而不是先解释所有内容。
• 操作指南帮助有经验的读者完成任务，不绕弯子。
• 参考内容完整、易于浏览且结构一致。
• 说明性内容旨在帮助读者理解，不冒充操作流程。
• 将相关但不同的内容链接起来或分开，而不是混在一起。
• 输出语言与用户使用的语言一致，除非用户另有要求。
• 大多数说明性句子只有一个主句和一个核心观点。
• 已审阅超过 25 个词的句子，并确认其长度确有必要。
• 不包含可以拆开表述的嵌套限定语。
• 简洁没有删去约束、证据或例外。
• 每项声明保留原有的确定程度，且未添加新事实。
• 英文操作指南、参考内容和教程步骤遵循 references/ste-rules.md。
• 已使用 humanizer 技能或 references/ai-prose-tells.md 检查文案中常见的 AI 写作痕迹。