The Diátaxis compass¶

Magellanic is organised with Diátaxis, which identifies four distinct needs readers have. Every page serves exactly one of them. Mixing them makes pages harder to use and harder to maintain.

Ask two questions¶

If a draft answers more than one way, split it into separate pages and link them.

Some of these rules are checked automatically: a how-to's title must start with "How to", and a tutorial must list exactly one distribution (make frontmatter). Vale warns about choices offered in tutorials, hedging in how-to guides, step-by-step instructions in explanation, and opinions in reference pages. Treat each warning as a question: fix the page, or keep the phrase if it's a genuine exception.

The four types¶

Tutorials¶

A lesson: the reader learns by doing, guided by you.

• Produces a visible result at every step, from a clean, specified starting environment.
• Offers no choices or alternatives; uses one distribution and says which.
• Explains as little as possible and links to explanation pages instead.

How-to guides¶

Directions that take a competent reader through a real problem to a goal.

• Titled with the goal: "How to…".
• Starts from a stated situation and ends when the goal is reached.
• Handles realistic branches, such as differences between distributions.
• Doesn't teach fundamentals or list every option.

Reference¶

Technical description of the machinery: accurate, complete and neutral.

• Structured like the thing it describes, and consistent across sibling pages.
• Contains no instructions beyond minimal examples, and no opinions.
• Cites upstream sources and the versions checked.

Explanation¶

Discussion that builds understanding.

• Answers "why?" and "how does it fit together?": context, history, design, trade-offs.
• Contains no step-by-step instructions.

Topic clusters¶

A topic usually needs several types. Rather than mixing them on one page, write separate pages that link to each other:

explanation/network-security/netfilter.md          why, and how it's built
tutorials/network-security/first-firewall.md       a guided lesson
how-to/network-security/open-port-nftables.md      a task recipe
reference/network-security/nftables.md             syntax and options

Each page ends with a short Related section linking the others in its cluster.