Documentation structure
Overview
Sky Mavis developer documentation is structured into four distinct content types: tutorials, how-to guides, explanations, and references. The composition and structure of developer documentation follow a technical documentation framework called Diataxis. Each content type addresses a different user need, fulfills a different purpose, and requires a different approach to its creation.
Diataxis
The Diataxis framework defines a core content structure that addresses the different needs users have when consulting documentation.
The following sections provide a brief summary of each content type. For a more in-depth understanding of the reasoning behind this classification, we recommend reading the official Diataxis website.
Explanation
An explanation is a discussion that clarifies and illuminates a particular topic. Explanations are understanding-oriented.
Here are some attributes of well-written explanation documents:
- They explain a topic. Their goal is to help the reader understand the concept.
- They do not teach, instruct or include reference information. If you need to refer to a tutorial, how-to, or reference, point the reader to where they can find it, rather than replicating that information directly in the explanation.
- They provide background information and context to explain why things work the way they do, or why they are built the way they are.
- They include specific examples to illustrate the explanation.
How-to guide
A how-to guide is a direction that takes the reader through the steps required to solve a real-world problem. How-to guides are goal-oriented.
Here are some attributes of well-written how-to guides:
- They demonstrate how to complete a task.
- They assume the reader has enough context to begin the task.
- They describe the concrete steps necessary to complete a task, but these steps can be in the middle of a larger task.
- They do not explain concepts. Instead, they rely on other documents, such as explanations, to do that.
- They are adaptable to real-world use cases.
Reference
A reference is a technical description of the system and how to operate it. References are information-oriented.
Here are some attributes of well-written references:
- They are concise and to the point. They state, describe, and inform.
- They are consistent with other reference documents.
- They remain focused on describing their topic. They don’t explain or provide additional context from other sources.
- They 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.
Tutorial
A tutorial is a lesson that takes the reader by the hand through a series of steps to complete a project of some kind. Tutorials are learning-oriented.
Here are some attributes of well-written tutorials:
- They provide a learning experience, giving the reader something they can do.
- They get the reader started (they do not create an expert).
- They provide the reader with concrete steps to follow, and each step has a comprehensible result.
- They are reliable and consistent (they work for all users, every time).
- They focus on one way of doing the task. Alternative approaches are explored in other document types, such as how-to guides.