Quarkus 文档内容类型
Quarkus 文档分为四种不同的内容类型：概念、操作指南、教程和参考。Quarkus 文档的组成和结构遵循 Diátaxis 系统文档框架进行技术文档编写。每种内容类型解决不同的用户需求，实现不同的目的，需要不同的创建方法。
Diátaxis 文档框架
我们选择将 Quarkus 文档与 Diátaxis 文档框架[1]对齐，该框架定义了一个核心内容结构，用于满足用户在查阅文档时的不同需求。
图片来源：https://diataxis.fr/
下面是不同文档类型的简要总结，如果您想更多地了解这种分类背后的原理，建议阅读他们的网站。
概念指南（解释）
解释是讨论，用于阐明和解释特定主题。解释是面向理解的。
好的概念指南
-
侧重于解释主题。它们的目标是帮助读者理解概念。
-
不进行教学、指导或包含参考信息。如果您需要参考教程、操作指南或参考指南，请将读者指向可以找到它们的位置，但不要在您的概念指南中直接复制该信息。
-
提供背景信息和上下文，以解释为什么事情会这样运作，或者为什么它们会被这样构建。您可以引用设计决策、历史原因和技术限制来重申您的观点。
-
包含具体的例子来说明解释，但避免使解释本身过度依赖于特定的技术或实现模式。
-
从多个角度分析概念，并与替代概念进行比较讨论（如果与读者的理解相关且有用）。
-
可以表达对您正在解释的概念相对于不同潜在用例或应用程序的优缺点的看法。
操作指南
操作指南是指导，引导读者完成解决实际问题所需的步骤。操作指南是目标导向的。
好的操作指南
-
指导（演练）或演示如何完成任务。
-
假设您有足够的上下文来开始任务。
-
描述完成任务所需的具体步骤，但这些步骤可能只是一个较大任务的一部分。
-
不解释概念，它们依靠其他文档（如概念）来完成此操作。
-
适用于实际用例。
-
实用（而非完整）。
参考指南
参考指南是对机器及其操作方法的技术描述。参考资料是信息导向的。
好的参考指南
-
简洁明了。它们陈述、描述和告知。
-
与其他参考指南尽可能保持一致。遵循模板有助于实现这一点。
-
始终专注于描述其主题。它们不解释或提供来自其他来源的额外上下文。
-
提供示例或插图，以帮助读者理解所描述的内容。
-
保持更新。虽然配置参考资料是生成的，但描述如何应用配置的扩展参考必须准确才能有用。
教程
教程是课程，通过一系列步骤引导读者完成某种项目。教程是学习导向的。
好的教程
-
提供学习体验，让读者可以做一些事情。
-
让读者入门（他们不会创造专家）。
-
为读者提供具体的步骤，每个步骤都有一个可以理解的结果。
-
可靠且一致（它们每次都适用于所有用户）。
-
仅包含完成任务所需的信息。它们委托给其他文档类型（概念或参考）以提供额外的上下文。
-
专注于一种完成任务的方式。替代方法在其他文档类型中进行探索（例如，操作指南）。
