Skip to content
Skills Library
Documents & office · Writing

ark-documentation

/ark-documentation

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.

Licence
Apache-2.0
Last repository change
23.10.2026

Assessment and security

95/ 100Class: good
Format20 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

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.

Original author 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.

How it works

  1. When to use this skill
  2. Ark's Diataxis structure
  3. The four quadrants
  4. Decision guide
  5. Hub pages
  6. Personas
  7. Writing guidelines
  8. Reference page structure
  9. Accuracy: verify against the source
  10. Build and preview before pushing
Original SKILL.md headings · 256 lines, 1,430 words
SKILL.md preview
---
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:

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

- [Diataxis Framework](https://diataxis.fr/)
- [Issue #338](https://github.com/mckinsey/agents-at-scale-ark/issues/338)
- [PR #620](https://github.com/mckinsey/agents-at-scale-ark/pull/620)

Versions

The database has no other skills named ark-documentation.

Database snapshot: 13.11.2026 · package version 9a7ce3ad1c4b (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90writing-documentation-with-diataxis
    Applies the Diataxis framework to create or improve technical documentation. Use when being asked to write high quality tutorials, how-to guides, reference docs, or explanations, when reviewing documentation quality, or when deciding what type of documentation to create. Helps…
  • 100diataxis-write-docs
    Draft or revise project documentation for the reader's purpose using Diataxis. Use for writing tutorials, how-to guides, reference, or explanation; use diataxis-organize-docs for reorganizing an existing documentation collection.
  • 100make-docs
    Create, edit, and validate technical documentation using the Diataxis framework. Use when writing tutorials, how-to guides, reference docs, or explanations. Use when reviewing or auditing existing documentation for structural correctness. Use when deciding what type of document…
  • 100diataxis
    Four-quadrant documentation framework. Produces tutorials (learning by doing), how-to guides (goal-oriented tasks), reference documentation (authoritative description), and explanation (conceptual understanding) using the Diataxis methodology. Invoke when creating new…
  • 100diataxis
    Helps maintain documentation pages based on the Diataxis method. Analyzes existing docs, classifies pages into tutorials/how-to/explanation/reference categories, identifies gaps, and helps create or restructure documentation following Diataxis principles. Use when user mentions…
  • 90Ark Analysis
    Analyze the Ark codebase by cloning the repository to a temporary location. Use this skill when the user asks questions about how Ark works, wants to understand Ark's implementation, or needs to examine Ark source code.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.