Diataxis称自己为“技术文档创作的系统方法”。简而言之，它是构建文档的框架。它将读者——我们为之编写文档的人——的需求作为优先事项和文档创建的基石。 Diataxis的中心是四种不同的用户需求和四种相应的文档形式：操作指南、教程、参考资料和解释。 资料来源：Diataxis.fr Diataxis不仅解决了文档编写的内容问题（写什么），还解决了风格（如何写）和架构（如何组织）。 虽然每个文档的主要焦点都是为读者带来价值，并使其易于阅读、理解和搜索信息，但Diataxis对您的团队成员——文档创建者和维护者——也非常有价值。它是轻量级的，易于理解，并且在应用中非常简单。 Diataxis文档类型 Diataxis最重要的基石之一是文档类型之间的明确区别。作者说，你不能模糊他们之间的界限。让我们看看Diataxis提供了什么。 教程 Diataxis将教程描绘成一种面向学习的实践体验，在导师（特定文档的作者）的指导下进行。 教程旨在教学，以便用户可以获得新的知识和技能。这种文档不是简单地帮助用户完成任务，而是教他们一些关于你的工具的新东西——无论是它的整体功能还是一个特定的特性。 好的教程很少，因为制作一个好的教程是一项相当具有挑战性的任务。除了一个教程要成为一个好的学习体验需要满足的明显标准之外，作者必须清楚地理解用户必须学习的东西和他们必须做的东西之间的区别和关系。因为人做的不一定是学到的。通过做某事，他们获得了理论知识和对事物如何工作以及如何相互联系的理解。他们学习事物的名称、工具的使用、工作流程、概念、命令等等。 我们经常看到这样的短语“在这篇文章中，你将学习如何……”但问题是，你无法知道用户会学到什么，不会学到什么。而这也是你作为教程创作者必须解决的教学问题。不要试图去教。相反，允许学习发生，它会发生的。通过给你的读者事情做，你会让他们学习。 一个好主意是从一开始就向读者展示他们将要做的事情。告诉他们为什么这个教程存在，他们将做什么。记住，你不知道他们会学到什么，你也不能指望每个人都学到同样的东西。 当设计教程，尤其是长教程时，优先考虑成功表演的体验并始终如一地向用户提供所有关键步骤的结果是至关重要的。不要让他们盲目按照说明去做；很难遵循你不理解的步骤。如果读者能看到因果关系，他们就会开始建立联系，理解事物是如何运作的。 你可以为你的读者做的另一件事是鼓励重复。尝试使特定的步骤及其结果可以重复，以便用户可以进行实验。 最难抵制的诱惑之一是，当事物和概念出现在教程中时，就开始解释它们。重要的是不要转向解释事物和概念，因为教程不是解释的地方；这有完全不同的文档形式。用户专注于他们正在做的事情，所以不要剥夺他们的注意力。很多时候，指南中间过多的解释只会打乱工作流程。但是如果你觉得你绝对必须解释某事，包括一个解释的链接，这样额外的信息就不会妨碍你做。 虽然关注一般模式和概念似乎是个好主意，但事实并非如此。把你的教程集中在具体的事情和行动上。不要认为你会剥夺你的用户更广泛的体验；事实上，从例子中感知一般模式是我们人类擅长的事情。共性总是从特殊性中产生，这就是你的学习应该如何组织。 当专注于一个特定的主题时，忽略选项和替代方案。这将使你的教程更简短，更简洁，它将保持读者的注意力。 操作指南 虽然相似，但操作手册与教程完全不同。这些简洁的说明不是以学习为导向的，而是以目标为导向的。它不教；它的目标不是允许学习，而是帮助用户完成一些事情。 一份好的操作指南是为用户而写的，而不是为机器而写的。 它定义了用户的需求，并帮助他们执行任务，从而获得意义和目的，解决问题，实现实际目标等。 它们描述了一个逻辑顺序的步骤——用户需要采取的行动来达到他们的目标——所以保持自然的流动而不突然跳跃是很重要的。和省略不必要的一样重要。与教程相比，操作指南不一定是全面的端到端体验；它们的实际用途要重要得多。 此外，除了解决特定问题之外，一大堆精心编写的操作指南展示了该产品的功能。 参考文献 在所有Diataxis文档类型中，引用可以说是最容易理解的。这种类型的内容是为那些在工作中需要命题或理论知识的用户设计的。此外，参考资料集中在它们描述的产品上，而操作指南和教程集中在用户的需求上。它可以是对选项、API或函数引用等的描述。 应该是对产品的中性描述，这往往很难做到。和往常一样，不要试图包括与产品互动的步骤或解释；还有其他地方可以这样做。提供例子就足够了；这将有助于读者理解参考文献，并帮助他们避免从他们正在做的工作中分心。参考文献应该简洁，排除任何歧义。 引用特别有用，当它被标准化时，它的工作做得特别好。采用模式，使你的参考一致。 解释 解释是一种面向理解的文档类型。这是谈论替代方案的最佳场所：反例或对同一问题的不同方法。但是避免给出指示或技术描述；在你的文档中还有其他地方。 解释是一种更开放的文档形式，类似于讨论，而不是教程、操作指南和参考资料，它们有明确定义的范围。所以可能不太清楚从哪里开始，如何结束。在这种情况下，在头脑中有一个“为什么”的问题会有所帮助：你想为你的读者提供背景信息，并增加他们对特定主题的理解。 Diataxis如何帮助我们在ClickHelp上制作更好的文档 作为专业文档软件的开发人员，我们ClickHelp一直理解好文档的重要性。但是，俗话说，鞋匠的孩子总是光着脚走。在早期，当我们是一个较小的团队时，我们缺乏一个专门的专业人员来为我们的产品编写文档，所以每个人都参与了它的创建：开发人员、技术支持、营销人员，甚至创始人。每个人都尽了最大努力，但不幸的是，一致性是不可能的。随着时间的推移，情况变得更糟，因为没有强大基础和结构构建的文档像滚雪球一样变成了难以找到和消化的杂乱无章的信息。 一旦我们决定必须做些什么，我们就开始了重组和重写整个文档的大规模项目。我们寻找一个合适的解决方案作为我们文档的基础，我们发现了Diataxis。它看起来简单，容易理解，而且很适合我们的需要。 首先，我们确定了文件现状中的主要问题： 缺乏清晰的结构。文档是结构化的，但是结构并不直观。浏览目录并不容易。 信息杂乱的话题。有时一个主题可能会很长，里面塞满了许多不同的信息，比如功能描述、特定案例的操作方法、参考资料等等。因此，很难理解在哪里可以找到您需要的特定信息。 一旦我们确定了问题，必须做什么就很清楚了：我们重新设计了整个文档结构。 因为我们已经有了很多关于我们产品的材料，所以我们考虑了我们可以在哪些类别中销售它；我们让我们的内容创造结构，就像Diataxis规定的那样。 一旦我们有了根级的部分主题，我们就写那些；这是一个解释每个特定概念的完美地方，这样读者可以在深入了解细节之前熟悉ClickHelp是什么以及如何工作的更高层次的概念。 从那时起，这个过程一直持续到今天：我们正在寻找什么是流行的，什么是缺失的，什么是不起作用的，并精确地改进它。我们处理每一项文档任务时都考虑到了Diataxis。仍然有一些旧文档留下，但是我们也会慢慢地但是稳步地改进它。 结论 我们采用Diataxis框架的经验已经证明了它在转变文档可用性方面的价值。通过将内容分类为与学习需求相匹配的不同类型，并清晰地组织信息，我们使用户能够更容易地找到并应用正确的材料。 自从围绕教程、操作方法、参考资料和解释进行重组以来，我们收到的关于定位内容的问题少了很多，并且听到了关于改进后的帮助体验的积极反馈。一点一点地，我们继续改进文档，但是我们对Diataxis的采用已经为用户和作者带来了显著的改善。 因此，如果您正在寻找一种更好地将用户体验与用户需求结合起来的方法，我们鼓励您考虑Diataxis或类似的结构化创作方法。 如果您正在寻找创建优秀文档的工具，请务必免费试用ClickHelp，体验为技术写作成功而优化的强大功能。 祝你的技术写作好运！ 单击帮助团队 跨平台和设备创作、托管和交付文档