ark-documentation

name	ark-documentation
description	Guidance for structuring Ark documentation using the Diataxis framework. Use this skill when creating new docs, deciding where content belongs, reviewing documentation PRs, or restructuring existing documentation.

Ark Documentation

Guidance for structuring Ark documentation using Diataxis adapted for Ark's needs.

When to use this skill

• Creating new documentation
• Deciding where content belongs
• Reviewing documentation PRs
• Restructuring existing documentation

Ark's Diataxis structure

docs/content/
├── Introduction
├── Quickstart
├── Tutorials          → Linear learning paths
├── How-to Guides      → Task-oriented, by persona
├── Core Concepts      → Understanding "why" and "how"
├── Reference          → Factual lookup material
├── Marketplace        → External link
└── Disclaimer

Terminology

Diataxis	Ark Term	Why
Explanation	Core Concepts	More accessible

The four quadrants

1. Tutorials (learning-oriented)

Purpose: Hands-on lessons for newcomers.

Characteristics:

• Linear, numbered paths (1, 2, 3...)
• Single prescribed path - no choices
• Frequent visible results
• Ends with "Next step" → How-to Guides

Writing style:

• Use "we" language
• Don't explain - link to Core Concepts

Content belongs here if:

• It teaches a skill through doing
• Reader is studying, not working
• Success requires following steps in order