ark-documentation

Ark ドキュメント

Ark のニーズに合わせた Diataxis を使用して、Ark のドキュメントを構成するためのガイドです。

このスキルを使用する場面

• 新しいドキュメントを作成するとき
• コンテンツの配置先を決めるとき
• ドキュメントの PR をレビューするとき
• 既存のドキュメントを再構成するとき

Ark の Diataxis 構成

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

用語

Diataxis	Ark の用語	理由
Explanation	コアコンセプト	より理解しやすいため

4 つのカテゴリー

1. チュートリアル（学習指向）

目的：初めてのユーザー向けの実践的なレッスンです。

特徴：

• 直線的で番号付きの手順（1、2、3…）
• 指定された単一の手順。選択肢はありません
• 目に見える結果を頻繁に示します
• 「次のステップ」で終了し、ハウツーガイドへ誘導します

文体：

• 「私たち」という表現を使います
• 解説はせず、コアコンセプトへのリンクを示します

次の場合は、ここにコンテンツを配置します：

• 実践を通じてスキルを教える
• 読者が作業中ではなく学習中である
• 成功するには手順を順番どおりに実行する必要がある

例：クイックスタート、ダッシュボードの実行、新しいプロジェクトの開始、完全な実例

---

2. ハウツーガイド（タスク指向）

目的：特定のタスクを完了できるよう、経験のあるユーザーを支援します。

ペルソナ別に整理：

Ark を使用した開発（アプリケーション開発者）

• モデルの設定、エージェントの作成、チームの調整、クエリの実行、ツールの追加。

Ark の拡張（コントリビューター）

• サービスのローカルでのビルド、API の実装、A2A サーバーのビルド、テストの追加。

Ark の運用（オペレーター／SRE／セキュリティ）

• プラットフォーム運用：プロビジョニング、デプロイ
• CI/CD とサプライチェーン：ビルドパイプライン
• セキュリティと保証：ペネトレーションテスト、コード分析

文体：

• 目標指向：「X をしたい場合は、Y を実行します」
• 十分な知識があることを前提とします
• 教えるのではなく、チュートリアルまたはコアコンセプトへのリンクを示します

次の場合は、ここにコンテンツを配置します：

• 読者に完了すべき特定のタスクがある
• 読者が学習中ではなく作業中である

---

3. コアコンセプト（理解指向）

目的：Ark とは何か、どのように設計されているか、そしてその理由を説明します。

トピック：

• Ark とは何か、どのように動作するか。
• 効果的なエージェント型システムの設計。
• プラットフォームアーキテクチャのコンセプト。
• 拡張性のコンセプト。
• セキュリティとアイデンティティのコンセプト。

文体：

• 論述的：「X の理由は…です」
• コンセプト同士のつながりを示します
• 設計上の決定に至った背景を示します

次の場合は、ここにコンテンツを配置します：

• 「なぜ」または「どのように動作するか」という問いに答える
• 読者が設計、拡張、運用の方法を検討している
• コンテンツが手順ではなく背景情報を提供する

---

4. リファレンス（情報指向）

目的：事実を調べるための資料です。

種類別に整理：

• インターフェイス：Ark API、Broker Service。
• Kubernetes API：CRD、リソース。
• システムの動作：クエリ実行、関係。
• 運用：アップグレード、トラブルシューティング。
• プロジェクト：コントリビューター。

文体：

• 簡潔で、事実に基づき、中立的
• 構成を製品に合わせます
• 指示、解説、意見は含めません

次の場合は、ここにコンテンツを配置します：

• 何かが何であるかを説明する
• 読者が特定の詳細を調べる必要がある
• コンテンツが通読されるのではなく、必要に応じて参照される

---

判断ガイド

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

ハブページ

ハブページは、ファイルを移動せずにコンテンツへのリンクを掲載します。

• tutorials.mdx - チュートリアルを順番に一覧表示します。
• how-to-guides.mdx - ペルソナ別に分類します。
• core-concepts.mdx - トピック別に分類します。
• reference/index.mdx - 種類別に分類します。

ハブページでは、次のことを行います。

• 目的を 1 文で説明します。
• リンクを論理的に分類します。
• コンテンツを重複させません。

ペルソナ

ペルソナ	セクション
エンドユーザー	クイックスタート、チュートリアル
エージェントビルダー	チュートリアル、ハウツー（開発）
プラットフォームエンジニア	ハウツー（運用）、リファレンス
コントリビューター	ハウツー（拡張）、コアコンセプト

執筆ガイドライン

用語集

• 製品名は Ark と表記します。先頭は大文字の A、その後は小文字の rk です。ARK と表記してはいけません。これはリポジトリの CLAUDE.md に準拠しており、レビューで確認されます。

全般的なスタイル

• 簡潔で率直に書きます。
• 平易な言葉を使います。
• 説明は1〜2文にまとめます。
• 能動態を使います。「エージェントを作成する」と書き、「エージェントが作成されます」とは書きません。
• 「ARK」ではなく「Ark」と書きます。
• アメリカ英語を使います。
• 列挙ではオックスフォードコンマを使います。

箇条書き

• 最初の語を大文字で始め、末尾にピリオドを付けます。
• 番号付きリストは、手順の順序を示す場合、または後で項目に言及する場合にのみ使います。

大文字表記

• 固有名詞（製品名、ツール名、サービス名）のみ大文字で始めます。
• タイトルにはセンテンスケースを使います。「An introduction to data visualization」のように書き、「An Introduction to Data Visualization」とは書きません。
• cloud、internet、machine learning、advanced analyticsは大文字で始めません。

見出し

• 動名詞を避けます。「Getting started」ではなく「Get started」、「Customizing a layout」ではなく「Customize a layout」とします。
• 検索で見つけやすい、短く具体的なタイトルにします。

手順

• 命令形を使います。「設定手順を完了します」と書きます。
• 「please」は使いません。
• 受動態は使いません。「手順を完了します」と書き、「手順を完了する必要があります」とは書きません。

リンク

• 内容が分かるハイパーリンクにします。Learn how to [contribute to Ark](url)のように書きます。
• To contribute, see [here](url)とは書きません。

避ける表現

• 見出しでの動名詞。
• 地域によって伝わらないことがある口語表現。
• 「leverage」「utilize」「facilitate」などのビジネス用語。

混在させない内容

次の項目には入れない	次の内容
チュートリアル	解説、選択肢。
ハウツーガイド	教育的な内容、網羅的なリファレンス。
コアコンセプト	手順、リファレンス。
リファレンス	手順、解説。

リファレンスページの構成

CRDおよびサービスのリファレンスページでは、一貫したテンプレートを使います。reference/resources/query.mdx、team.mdx、tools.mdxをモデルとして使います。

1. Frontmatter — titleと、"<Kind> CRD reference — ..."形式のdescription。
2. 概要 — リソースの説明を1段落で記述し、タスク指向のユーザーガイドの手順にリンクします。このページがフィールドごとのリファレンスであることを明確に伝えます。
3. ## Spec — 注釈付きのYAML例を1つ掲載し、コメントを必須項目と任意項目に分けます。
4. ## Fields — Field | Type | Required | Descriptionの列を持つ表を掲載します。列挙値、デフォルト値、フィールド間のルールを含めます。
5. トピック別セクション — 必要に応じて、戦略、パラメーター、認証などを掲載します。
6. ## Status — ステータスのYAMLブロック、### Status fieldsの表、フェーズの列挙値が存在する場合は### Phasesの表、そしてkubectl getが表示する列の名前を記載した### Print columnsの行を掲載します。
7. ## Related — 関連するページへのリンクを掲載します。

概要／インデックスページでは、すべてのリソースをKindとAPIバージョンとともに一覧にする表を1つ使います。内容が重複する概要ページを別に設けないでください。1つのトピックにつき1ページにします。サービスAPIも同様です。サービスごとにリファレンスページを1つ（Ark API、Broker Service）用意し、組み込みのOpenAPI／Swaggerを常に最新の信頼できる情報源として位置付けます。

正確性：ソースコードと照合してください

リファレンスドキュメントは、意図や記憶ではなく、コードに忠実でなければなりません。もっともらしく読めても、内容が間違っているページはあります。これは最もよくある不備です。リファレンスページを作成またはレビューする前に、すべての記述を確認してください。

• フィールド、列挙値、デフォルト値 — ark/api/v1alpha1/*_types.go の Go 型と、ark/config/crd/bases/ の生成済み CRD を確認してください。+kubebuilder:validation:Enum、+kubebuilder:default、および json タグが正式な定義です。既存の説明文ではありません。
• 動作と制約 — コントローラーと Webhook（ark/internal/controller/、ark/internal/validation/）を確認してください。移行先、同一名前空間と別名前空間での解決の違い、検証ルールはここに記載されています。例：非推奨の graph チーム戦略は sequential に移行します（エッジは破棄されます）。selector ではありません。これは validation/defaults.go で確認できます。レビュー担当者が別のことを主張していても、必ず確認してください。
• 稼働中のクラスター — 利用できる場合は、kubectl explain、kubectl get <kind>（表示列の確認用）、実際のリソース YAML で確認してください。サービス API の場合は、稼働中のサービスの /openapi.json と Swagger を確認してください。
• バージョンとリリースに関する記述 — カレンダーではなく、リリースタグを確認してください。git grep <pattern> <tag> で変更時期を確認でき、git merge-base --is-ancestor <commit> <tag> で実際にリリースに含まれたかを確認できます。確認せずにセクションを「未リリース」としたり、バージョン（たとえば v0.2.0 は存在しません）を記載したりしないでください。

このセッションでの書き直しでは、架空のフィールド（spec.model、systemPrompt、spec.agents）、存在しない CLI コマンド（ark check、ark describe。正しくは make routes ではなく devspace run routes）、誤った移行先が多数見つかりました。いずれも、一見問題のないページに記載されていました。

プッシュ前にビルドしてプレビューする

• cd docs && npm run build（Turbopack）でビルドしてください。本番ビルドでは、開発サーバーが警告なしで許容する MDX と mermaid のエラーを検出でき、成功時にはページ数も表示されます。ビルドが正常に完了しない限り、ドキュメントの変更をプッシュしないでください。
• レンダリングされたページをプレビューしてください（開発サーバーとスクリーンショット）。Mermaid は遅延読み込みされるため、図までスクロールするか、キャプチャ時に十分な高さのビューポートを用意してください。
• 図と説明文は、重複させず、互いを補完するものにしてください。関連する内容を扱う 2 つのページ（例：コアアーキテクチャとクエリ実行フロー、またはコアコンセプトとコアアーキテクチャの図）がある場合は、相互にリンクし、内容の繰り返しを避けてください。

参考資料

• Diataxis フレームワーク
• Issue #338
• PR #620