SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsark-documentation

ark-documentation

Writing & research

View repository

Updated 10-16 00:22

About this skill

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:

  1. Frontmatter — title and a description of the form "<Kind> CRD reference — ...".
  2. 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.
  3. ## Spec — a single annotated YAML example, comments grouped Required / optional.
  4. ## Fields — a table with columns Field | Type | Required | Description, including enum values, defaults, and cross-field rules.
  5. Topic sections as warranted (strategies, parameters, auth, …).
  6. ## 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.
  7. ## 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