Skip to main content

About 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.

See also

Was this helpful?
Happy React is loading...