| 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
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 API, Broker Service.
- Kubernetes API: CRDs, resources.
- 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 written Ark — capital A, lowercase
rk. Never ARK. This matches the repo's CLAUDE.md and is enforced in review.
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. |
Reference page structure
CRD and service reference pages follow a consistent template. Use reference/resources/query.mdx, team.mdx, and tools.mdx as the models:
- Frontmatter —
title and a description of the form "<Kind> CRD reference — ...".
- Intro — one paragraph on what the resource is, linking the task-oriented user-guide walkthrough; state plainly that this page is the field-by-field reference.
## Spec — a single annotated YAML example, comments grouped Required / optional.## Fields — a table with columns Field | Type | Required | Description, including enum values, defaults, and cross-field rules.- Topic sections as warranted (strategies, parameters, auth, …).
## Status — a status YAML block, a ### Status fields table, a ### Phases table where a phase enum exists, and a ### Print columns line naming the columns kubectl get renders.## Related — links to adjacent pages.
For an overview/index page, use one table listing every resource with its Kind and API version. Don't keep a second overlapping overview page — one topic, one page. The same applies to service APIs: one service, one reference page (Ark API, Broker Service), with the built-in OpenAPI/Swagger framed as the always-current source of truth.
Accuracy: verify against the source
Reference docs must be true to the code, not to intent or memory. Pages can read plausibly and still be wrong — this is the most common defect. Before writing or reviewing a reference page, verify every claim:
- Fields, enums, defaults — read the Go types in
ark/api/v1alpha1/*_types.go and the generated CRD in ark/config/crd/bases/. +kubebuilder:validation:Enum, +kubebuilder:default, and the json tags are authoritative — not the existing prose.
- Behavior and constraints — read the controller and webhooks (
ark/internal/controller/, ark/internal/validation/). Migration targets, same- vs cross-namespace resolution, and validation rules live here. Example: a deprecated graph team strategy migrates to sequential (edges discarded), not selector — confirmed in validation/defaults.go. Verify even when a reviewer asserts otherwise.
- Live cluster — where one is available, confirm with
kubectl explain, kubectl get <kind> (for the print columns), and real resource YAML. For a service API, hit the running service's /openapi.json and Swagger.
- Version and release claims — check the release tags, not the calendar.
git grep <pattern> <tag> shows when something changed; git merge-base --is-ancestor <commit> <tag> confirms what actually shipped. Don't label a section "Unreleased" or cite a version (e.g. there is no v0.2.0) without checking.
This session's rewrites found extensive fictional fields (spec.model, systemPrompt, spec.agents), non-existent CLI commands (ark check, ark describe; it's devspace run routes, not make routes), and wrong migration targets — all in pages that looked fine.
Build and preview before pushing
- Build with
cd docs && npm run build (Turbopack). The production build catches MDX and mermaid errors the dev server silently tolerates, and prints a page count on success. Never push a docs change without a clean build.
- Preview the rendered page (dev server + screenshot). Mermaid renders lazily — scroll to the diagram or render a tall enough viewport before capturing.
- Keep diagrams and prose complementary, not duplicated. When two pages cover related ground (e.g. Core Architecture and Query Execution Flow, or the Core Concepts and Core Architecture diagrams), cross-link and defer rather than repeat.
References
