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

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.

• Design 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 behavior: 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

Lexicon

• The product is known as ARK rather than Ark.

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 .

• Don't write: To contribute, see here .

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