documentation

ドキュメント

ドキュメントはdocs/に置かれ、GitHub Flavored Markdownを使用し、Astro Starlightでレンダリングされ、Diátaxisに沿っています。

Diátaxis フレームワーク

ドキュメントは、次の4つのDiátaxisタイプに分類します。

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

目的：初心者が自信をつけられるよう、特定の成果を達成する手順を案内します。

• ユーザーが作成または達成するものから始めます
• 最初から最後まで、明確な手順を示します
• 具体的な例と動作するコードを含めます
• 事前知識は最小限であることを前提とします
• うまくいく手順に焦点を当てます（例外的なケースや代替案は避けます）
• ユーザーが確認して使える、動作する成果物で締めくくります
• 命令形を使います：「ファイルを作成する」「コマンドを実行する」

避けること：概念の詳しい説明、複数の選択肢、トラブルシューティング

2. ハウツーガイド（目標指向）

目的：特定の現実的な問題を解決する方法、または特定のタスクを達成する方法を示します。

• タイトル形式：「[具体的な目標]を達成する方法」
• ユーザーが基本を理解していることを前提とします
• 1つの問題を解決する実践的な手順に焦点を当てます
• 必要なコンテキストを含めつつ、焦点を保ちます
• 本当に役立つ場合に限り、複数の方法を示します
• 目標を達成した時点で終えます
• 命令形を使います：「設定を構成する」「次の内容を追加する」

避けること：基礎の指導、あらゆる詳細の説明、網羅的な内容

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

目的：システムについて、正確で完全な技術的説明を提供します。

• 構造別に整理します（CLI コマンド、構成オプション、API エンドポイントなど）
• 包括的で信頼できる内容にします
• すべての項目で形式を統一します
• 技術的な正確さを最優先します
• すべてのパラメーター、オプション、戻り値を含めます
• 説明的な文体を使います：「このコマンドは次の値を受け取ります」「文字列を返します」
• 物語的な説明や解説は最小限にします

避けること：手順、チュートリアル、使い方に関する意見

4. 解説（理解指向）

目的：トピックを明確にして掘り下げ、理解を深めます。

• なぜそのようになっているかを説明します
• 設計上の判断とトレードオフを説明します
• 背景やコンテキストを示します
• 概念を関連付け、メンタルモデルの形成を助けます
• 代替案とその影響について説明します
• 叙述的な文体を使います：「このアプローチは〜を提供します」「エンジンは〜を使用します」

避けること：段階的な手順、網羅的なリファレンス資料

全般的なスタイルガイドライン

• トーン：中立的で技術的、宣伝調にしない
• 文体：「we」「our」「us」は避けます（「the tool」「this command」を使います）
• 見出し：太字のテキストを見出しとして使わず、Markdownの見出し構文を使います
• リスト：長い箇条書きは避け、構造を持たせた文章を優先します
• コードサンプル：最小限で焦点を絞り、関連がない場合は任意のフィールドを省きます
• 言語タグ：YAMLフロントマターを含むエージェント型ワークフローのスニペットにはawを使います

ワークフローのコードブロック例：

on: push
# Your workflow steps here

GitHub Flavored Markdown の構文

ドキュメントファイルはGitHub Flavored Markdownを使用し、Astro Starlightでレンダリングします。主な構文要素は次のとおりです。

フロントマター

すべてのドキュメントページにフロントマターを含める必要があります。

title: Page Title
description: Brief description for SEO and navigation

GitHub アラート

メモ、ヒント、警告、注意にはGitHubのアラート構文を使います。

> [!NOTE]
> Important information the reader should notice.

> [!TIP]
> Helpful advice for the reader.

> [!WARNING]
> Warning about potential issues or pitfalls.

> [!CAUTION]
> Critical warning about dangerous operations.

> [!IMPORTANT]
> Key information users need to know.

コードブロック

• 言語タグを付けて構文をハイライトします
• ファイル名にはtitle属性を追加します：```yaml title=".github/workflows/example.yml"
• YAMLフロントマターを含むエージェント型ワークフローファイルにはaw言語を使います
• 行を折り返すにはwrapを追加します：```aw wrap

リンク

• 内部リンク：ドキュメントページ間では相対パスを使います
• 外部リンク：新しいタブで自動的に開きます
• リンクテキスト：説明的な文言を使い、「ここをクリック」は避けます

タブ

代替案（例：異なる言語、プラットフォーム）の表示にはタブを使います。

import { Tabs, TabItem } from '@astrojs/starlight/components';

<Tabs>
  <TabItem label="npm">
    ```bash
    npm install package
    ```
  </TabItem>
  <TabItem label="yarn">
    ```bash
    yarn add package
    ```
  </TabItem>
</Tabs>

カード

ナビゲーションや複数の選択肢の強調表示にはカードを使います。

import { Card, CardGrid } from '@astrojs/starlight/components';

<CardGrid>
  <Card title="Getting Started" icon="rocket">
    Quick introduction to the basics.
  </Card>
  <Card title="Advanced Usage" icon="setting">
    Deep dive into advanced features.
  </Card>
</CardGrid>

注意：コンポーネントは最小限にします。可能な場合は標準のMarkdownを優先します。

避けるべきコンテンツ

• 「主な機能」セクション
• 宣伝文句や売り文句
• 箇条書きの多用（構造化された文章を優先）
• すべてのオプションパラメーターを含む、冗長すぎる例
• ドキュメントの種類を混在させること（例：リファレンスのようになってしまうチュートリアル）

ドキュメントの肥大化を避ける

ドキュメントが肥大化すると明瞭さが損なわれ、内容を見つけにくくなります。よくある肥大化の種類は次のとおりです。

ドキュメントの肥大化の種類

1. 重複した内容：同じ情報が異なるセクションで繰り返されている
2. 箇条書きの多用：文章や表にまとめられる長いリスト
3. 冗長な例：同じ概念を示す複数の例
4. 冗長な説明：簡潔にできる、必要以上に長い説明
5. 繰り返しの構成：「何をするのか」／「なぜ役立つのか」というパターンの過度な使用

簡潔なドキュメントを書く

ドキュメントを編集する際は、次の点に注目してください。

箇条書きをまとめる：

• 長い箇条書きを、簡潔な文章や表に置き換える
• 異なる表現で同じことを述べている重複項目を削除する

重複をなくす：

• 繰り返されている情報を削除する
• 類似するセクションを統合する

冗長な文章を簡潔にする：

• 説明をより直接的で簡潔にする
• つなぎ言葉や冗長な表現を削除する
• 単語数を減らしながら、技術的な正確さを保つ

構成を標準化する：

• 「何をするのか」／「なぜ役立つのか」という繰り返しのパターンを減らす
• 多様で自然な表現を使う

コードサンプルを簡潔にする：

• コード例から不要な複雑さを取り除く
• 中心となる概念を明確に示すことに重点を置く
• 理解に不可欠でない定型コードやセットアップコードを省く
• 最小限でありながら、完全な例にする
• 現実的でありつつ、シンプルなシナリオを使う

例：修正前と修正後

修正前（冗長）：

### Tool Name
Description of the tool.

- **What it does**: This tool does X, Y, and Z
- **Why it's valuable**: It's valuable because A, B, and C
- **How to use**: You use it by doing steps 1, 2, 3, 4, 5
- **When to use**: Use it when you need X
- **Benefits**: Gets you benefit A, benefit B, benefit C
- **Learn more**: [Link](url)

修正後（簡潔）：

### Tool Name
Description of the tool that does X, Y, and Z to achieve A, B, and C.

Use it when you need X by following steps 1-5. [Learn more](url)

ドキュメント品質ガイドライン

1. 意味を保つ：重要な情報を決して失わない
2. 必要な箇所だけを修正する：精密に編集し、すべてを書き換えない
3. トーンを保つ：中立的で技術的なトーンを維持する
4. ローカルでテストする：リンクと書式が正しいことを確認する

ファイルの種類に応じた構成

• はじめに：チュートリアル形式
• ハウツーガイド：目的指向で、1つのガイドにつき1つのタスク
• CLI リファレンス：リファレンス形式で、コマンドを漏れなく説明
• 概念：理解を深めるための解説形式
• API リファレンス：リファレンス形式で、API を漏れなく説明