Overview of concepts underlying the structure and composition of Quarkus docs.

Content Types

We are aligning Quarkus docs with the Diátaxis documentation framework[1], which defines a core content structure that addresses the different needs users have when consulting docs. 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)

Explanation is discussion that clarifies and illuminates a particular topic. Explanation is understanding-oriented.

Good concept guides:

  • are about a topic, and aim to provide the reader with information that helps establish a deeper understanding of that topic.

  • make connections to other things, if it helps explain the topic.

  • provide background and context to help explain why.

  • can consider alternatives or counter-examples, if it helps explain the topic.

  • do things other parts of the documentation do not; rely on references, tutorials, and how-to guides to perform their roles.

How-To guides

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

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

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 (e.g. a how-to guide).


1. Procida, D. Diátaxis documentation framework. https://diataxis.fr/