Quarkus documentation content types
Quarkus 文档被构建成四种独特的内容类型:概念、方法、教程和参考。Quarkus 文档的组成和结构遵循 Diátaxis 系统文档框架,用于技术文档编写。每种内容类型都会解决不同的用户需求、实现不同的目的,并且需要采取不同的方法来创建。
Quarkus documentation is structured into four distinct content types: concepts, how-tos, tutorials, and references. The composition and structure of Quarkus docs follow the Diátaxis systematic documentation framework for technical documentation authoring. Each content type resolves a different user need, fulfills a different purpose, and requires a different approach to its creation.
Diátaxis documentation framework
我们选择将 Quarkus 文档与 Diátaxis 文档框架“6”对齐“5”,它定义了一种核心内容结构,该结构满足用户在查阅文档时会遇到的不同需求。
We chose to align Quarkus docs with the Diátaxis documentation frameworkD. Diátaxis documentation framework. [role="bare"https://diataxis.fr/], which defines a core content structure that addresses the different needs users have when consulting docs.
Image credit: [role="bare"]https://diataxis.fr/
以下是不同文档类型的一个简短摘要,但是如果你想更深入地了解此分类背后的原因,那么值得花时间阅读我们的网站。
What follows is a brief summary of the different document types, but their site is worth a read if you want to understand more of the reasoning behind this classification.
Concept guides (Explanation)
说明是 discussion,对特定主题进行澄清和讲解。说明是 understanding-oriented。
Explanation is discussion that clarifies and illuminates a particular topic. Explanation is understanding-oriented.
优秀的概念指南:
Good concept guides:
-
focus on explaining a topic. Their goal is to help the reader understand the concept.
-
do not teach, instruct or include reference information. If you need to refer to a tutorial, how-to, or reference guide, point the reader to where they can find it, but do not replicate that information directly in your concept guide.
-
provide background information and context to explain why things work the way they do, or why they are built the way they are. You can cite design decisions, historical reasons, and technical constraints to reaffirm your points.
-
include specific examples to illustrate the explanation, but avoid making the explanation itself overly dependent on a specific technology or pattern of implementation.
-
analyze the concept from multiple perspectives and draw comparisons with alternative concepts discuss if it is relevant and useful for the reader’s understanding.
-
may express opinions about advantages and drawbacks of the concept that you are explaining relative to different potential use cases or applications.
How-to guides
操作方法指南是 directions,指导读者完成解决实际问题所需的步骤。操作方法指南是 goal-oriented。
How-to guides are directions that take the reader through the steps required to solve a real-world problem. How-to guides are goal-oriented.
优秀的如何操作指南:
Good how-to guides:
-
guide (walk-through) or demonstrate how to complete a task.
-
assume you have enough context to begin the task.
-
describes the concrete steps necessary to complete a task, but these steps could be in the middle of a larger task.
-
do not explain concepts, they rely on other documents (like concepts) to do that.
-
are adaptable to real-world use cases.
-
are practical (rather than complete).
Reference guides
参考指南是“1”机器以及如何操作它的文档。参考材料是“2”。
Reference guides are technical descriptions of the machinery and how to operate it. Reference material is information-oriented.
优秀的参考指南:
Good reference guides:
-
are concise and to the point. They state, describe, and inform.
-
are consistent (to the extent possible) with other reference guides. Following the template helps here.
-
remain focused on describing their topic. They don’t explain or provide additional context from other sources.
-
provide examples or illustrations that help readers understand what is being described.
-
are kept up to date. While configuration reference material is generated, extension references that describe how configuration should be applied must be accurate to be useful.
Tutorials
教程是“3”文档,它指引读者逐步完成某种项目。教程是“4”。
Tutorials are lessons that take the reader by the hand through a series of steps to complete a project of some kind. Tutorials are learning-oriented.
优秀的教程:
Good tutorials:
-
provide a learning experience, giving the reader something they can do.
-
get the reader started (they do not create an expert).
-
provide the reader with concrete steps to follow that each have a comprehensible result.
-
are reliable and consistent (they work for all users, every time).
-
include only enough information to complete the task. They delegate to other documentation types (concepts or reference) to provide additional context.
-
focus on one way of doing the task. Alternative approaches are explored in other document types (a how-to guide, for example).