Getting Started with diataxis

In this tutorial we will set up a documentation set, write two pages of different types, and read the map that shows where they sit.

Initialize the set

Run this from the root of a project:

diataxis init

The command writes diataxis.yml and makes a docs directory. The output names both:

diataxis: wrote diataxis.yml
diataxis: pages live in docs

Write a tutorial

Every page declares a type. This one is a tutorial:

diataxis page create "Getting started with acme" -T tutorial \
  --description "Install acme and run the first job"

The command prints the page id and its type:

getting-started-with-acme (tutorial)

The id comes from the title. It is the file stem, and it becomes the page’s published path, so it carries no random prefix.

Write a how-to guide

Now a page for a reader who is already competent:

diataxis page create "How to rotate the signing key" -T how-to

Notice that the title starts with “How to”. A how-to title states a goal, so a reader scanning a list sees which page does the thing they want. Try it without the words:

diataxis page create "Rotating the signing key" -T how-to
diataxis check

The check reports the title:

fault  rotating-the-signing-key     a how-to title states a goal: "Rotating the signing key" does not start with "How to"

Remove that page again:

diataxis page delete rotating-the-signing-key

Read the map

diataxis map

The map prints the four types in Diátaxis order, with the pages under each:

docs

tutorial  informs action, serves acquisition of skill — 1 page(s)
  getting-started-with-acme    Getting started with acme

how-to  informs action, serves application of skill — 1 page(s)
  how-to-rotate-the-signing-key  How to rotate the signing key

reference  informs cognition, serves application of skill — 0 page(s)
  (none)

explanation  informs cognition, serves acquisition of skill — 0 page(s)
  (none)

Two quadrants hold pages and two are empty. That is what the map is for: a list of six pages hides a gap, and a grid shows it.

Check the set

diataxis check

The two empty types come back as advice rather than faults:

advice  the set    no reference pages
advice  the set    no explanation pages

You have built a typed documentation set, and you can see what it is missing.