Diátaxis 框架提出文档编写的十二项原则

文档的功能是服务于某一技艺的实践者。

技艺是一个技能领域。文档的存在是为了指导需要获取并运用一套技能的人。文档在多大程度上满足了他们的需求，就在多大程度上是成功的。

技艺或技能领域可以是狭窄的，由某个产品或工具的使用来界定；也可以是宽泛的，由某个学科或职业来界定。（技艺的例子：使用一门编程语言、制衣、驾驶某一特定机型、作为飞行员一般而言。）

文档的功能决定了它的架构。

文档需要一种服务于其功能的架构——一种结构形式。这种结构必须反映出对技能本身的系统性理解，以及对某一技能领域中实践者需求的理解。

Diátaxis 文档框架基于对技能在两个维度上的分析：理论/实践与获取/应用，并以此定义了一张由不同类型文档构成的架构地图，这些类型彼此之间处于相互关联之中。

任何一份文档都归属于整体中唯一正确的位置。

对于任何一份文档，都应该能够确定它在结构中的恰当位置，以及它与其他文档内容的关系。应当能够有把握地做到这一点，所用的逻辑原则正是确定文档架构的那些原则。

就产品而言，文档是产品本身的一部分。

一个产品若缺少用户所需的文档，就不仅仅是可用性差，而是字面上不完整。

产品的文档必须构成一个自包含、统一的整体。

产品的文档应当是一套具有共同目的和范围的作品，作为一个连贯的整体来构思、撰写、维护和呈现。所有想要达到文档地位的材料都需要整合进这套作品之中。

产品文档有刻意的范围。

产品文档不仅仅是与产品相关的书面材料的集合。它必须有目的、有意图，并依据一种与产品自身目的和意图相一致的愿景来开发。

对于会演进的产品——比如软件产品——文档有生命周期。文档的生命周期包括其创建、评审、维护和删除。创建了却未经评审、更新或删除的文档，比无用还糟。

只能有单一的事实来源。任何一份文档内容只允许存在于一个上下文中。（尽管把某份产品文档的一部分从一个上下文复制到另一个上下文很诱人，但这实际上等于保证了它在所有实例中的权威性都被削弱。）

无论是来自暴露（引用和链接到本应比它更好的材料）还是来自期望（用户的要求），压力都会迫使文档改进。文档应当承受尽可能大的暴露和期望。（人们很容易通过在别处掩盖缺陷或弥补来补偿某处文档的不足。这或许能减少一时的尴尬，但也减少了带来改进的压力。这是一条恶性循环的一部分，在其中文档往往得不到改进。）

在产品生命周期中，开始创建文档永远不嫌早。当你有了可以记录的东西，就开始写。当你写了东西，就发布它。（人们很容易等待合适的时机，等你或别的什么“准备好了”。这属于——并且加剧了——一种错误态度，即认为文档追随它所指向的产品。事实上，创建文档不仅是达到“准备好”的一部分，它还能帮助更快达到那里，并达到更好的版本。）

没有维护计划的文档注定会腐坏。

除非有明确、有效的维护方案到位，否则文档必然会衰败。不应创建任何不会被维护的文档。（通常，创建一些满足眼前需求的临时内容看起来是件好事——确实可能如此，但绝不是在文档中。发布这类材料还有其他方式。）

文档中的连接是其稳健性的一部分。

文档内部及文档之间经过深思熟虑的链接构成了一个强大的知识网络，其中所有部分相互支撑。抓住每一个机会来构建这个网络。