Document Type

OpenNebula documentation is written following the Diátaxis framework.

Ideally, technical documents should conform to one of the four Diátaxis definitions:

• Tutorial
• How-to Guide
• Explanation
• Reference

The following table outlines the distinction between these documentation types. Before starting new documentation, consider which of these categories the new documentation most closely matches with.

Type	Description	Goal
Tutorial	Step-by-step instructions for performing a simple task in ideal conditions. Often used as a beginner’s or quick start document. Does not include explanations, and ideally provides the reader with a single pathway to follow to completion.	Induce the reader to learn by doing. Demonstrate the capabilities and potential of the product.
How-to	Practical guide to achieve a real-world goal, possibly including more than one component or product, and several options and pathways to follow to completion.	Aid the reader in the application of skills.
Explanation	A document focused on explanation provides high-level definitions for concepts, components, frameworks, interactions and purposes. Examples are overview documents.	Aid in acquiring knowledge and understanding.
Reference	Provide authoritative and complete technical information about a specific element (component, interface, configuration). Often follows a strict order, such as alphabetical order. May provide brief examples.	Provide an authoritative, trustworthy and complete reference for consultation when needed, akin to a dictionary. Not meant to be read sequentially.

Theoretically, these four types of documents are mutually exclusive. For example, tutorials, how-tos and reference documents don’t contain explanations or reference; explanation or reference documents don’t contain instructions, etc.

In practice most documentation does not conform 100% to these definitions (for example, it may be necessary to provide some contextual explanation in a how-to guide), but even so these categories remain useful, specially to avoid mixing different content types in a way that is counterintuitive or confusing.