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](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