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

Examples: Quickstart, Running the Dashboard, Starting a New Project, Complete Worked Example

---

2. How-to Guides (Task-Oriented)

Purpose: Help competent users complete specific tasks.

Organized by persona:

Build with Ark (Application Developers)

• Configure models, create agents, coordinate teams, run queries, add tools

Extend Ark (Contributors)

• Build services locally, implement APIs, build A2A servers, add testing

Operate Ark (Operators / SRE / Security)

• Platform operations: Provisioning, deploying
• CI/CD and supply chain: Build pipelines
• Security & assurance: Pen testing, code analysis

Writing style:

• Goal-oriented: "If you want X, do Y"
• Assumes competence
• Don't teach - link to Tutorials or Core Concepts

Content belongs here if:

• Reader has a specific task to complete
• Reader is working, not studying

---

3. Core Concepts (Understanding-Oriented)

Purpose: Explain what Ark is, how it's designed, and why.

Topics:

• What Ark is and how it works
• Designing effective agentic systems
• Platform architecture concepts
• Extensibility concepts
• Security and identity concepts

Writing style:

• Discursive: "The reason for X is..."
• Make connections between concepts
• Provide design decision context

Content belongs here if:

• It answers "why" or "how does this work"
• Reader is deciding how to design/extend/operate
• Content provides context, not procedures

---

4. Reference (Information-Oriented)

Purpose: Factual lookup material.

Organized by type:

• Interfaces: Ark APIs
• Kubernetes API: CRDs, Resources
• Evaluations: Guides, event-based evaluations
• System behaviour: Query execution, relationships
• Operations: Upgrading, troubleshooting
• Project: Contributors

Writing style:

• Austere, factual, neutral
• Structure mirrors product
• No instruction, explanation, or opinion

Content belongs here if:

• It describes what something IS
• Reader needs to look up specific details
• Content is consulted, not read cover-to-cover

---

Decision Guide

Is the reader LEARNING or WORKING?
│
├─ LEARNING (studying)
│   ├─ Hands-on, step-by-step? → TUTORIALS
│   └─ Understanding concepts? → CORE CONCEPTS
│
└─ WORKING (applying)
    ├─ Completing a task? → HOW-TO GUIDES
    └─ Looking up facts? → REFERENCE

Hub Pages

Hub pages link to content without moving files:

• tutorials.mdx - Lists tutorials in order
• how-to-guides.mdx - Groups by persona
• core-concepts.mdx - Groups by topic
• reference/index.mdx - Groups by type

Hub pages should:

• Explain purpose in one sentence
• Group links logically
• Not duplicate content

Personas

Persona	Sections
End users	Quickstart, Tutorials
Agent builders	Tutorials, How-to (Build)
Platform engineers	How-to (Operate), Reference
Contributors	How-to (Extend), Core Concepts

Writing Guidelines

General Style

• Be concise and direct.
• Use simple language.
• Keep descriptions to 1-2 sentences.
• Use active voice: "Creates agent" not "Agent is created".
• Write "Ark" not "ARK".
• Use US English.
• Use Oxford commas in lists.

Bullets

• Capitalize the first word and end with a period.
• Use numbered lists only for sequences of instructions or when referencing items later.

Capitalization

• Capitalize only proper nouns (product names, tools, services).
• Use sentence case for titles: "An introduction to data visualization" not "An Introduction to Data Visualization".
• Don't capitalize: cloud, internet, machine learning, advanced analytics.

Headings

• Avoid gerunds: "Get started" not "Getting started", "Customize a layout" not "Customizing a layout".
• Keep titles short and descriptive for search discoverability.

Instructions

• Use imperatives: "Complete the configuration steps."
• Don't use "please".
• Don't use passive tense: "Complete the steps" not "The steps should be completed."

Links

• Make hyperlinks descriptive: Learn how to [contribute to Ark](url).
• Don't write: To contribute, see [here](url).

Avoid

• Gerunds in headings.
• Colloquialisms (may not translate across regions/languages).
• Business speak: "leverage", "utilize", "facilitate".

What NOT to Mix

Don't put in...	This content...
Tutorials	Explanations, choices
How-to Guides	Teaching, complete reference
Core Concepts	Instructions, reference
Reference	Instructions, explanations

References

• Diataxis Framework
• Issue #338
• PR #620