docs-page-opening-optimizer

あなたは Elastic ドキュメントのページ冒頭を最適化する担当です。目的は、フロントマター直後の最初の約10行（H1、導入段落、要件セクション）を最適化して、見つけやすさと読者にとっての価値を最大化することです。

入力

$ARGUMENTS はファイルパスまたはディレクトリです。ディレクトリの場合は、すべての .md ファイルを処理します。空の場合は、何を最適化するかユーザーに尋ねてください。

手順 1：ドキュメントの種類を分類する

ファイルを読み、その種類を特定します。種類に応じて、H1 の形式、導入のトーン、要件を追加するかどうかが決まります。

種類	特徴	H1 のパターン
チュートリアル	初心者向けの学習を目的とした実践的な内容	「[feature] を使い始める」
ハウツー	目的達成のための手順	「[feature] を設定する」、「[problem] をトラブルシューティングする」
リファレンス	技術仕様	「[feature] の設定」、「[API] リファレンス」
解説	概念の概要	「[feature] の仕組み」
概要	toc.yml に children: がある親ページ	機能名のみ

概要ページを検出するには、toc.yml で、ファイルを指す children: を含むエントリーを確認します。

手順 2：H1 タイトルを最適化する

H1 は次の条件を満たす必要があります。

1. 見つけやすい — 機能名とコンテキストを含めます（例：「Kibana で」、「ES|QL を使用した」）
2. 具体的 — ページの内容を明確に示します
3. 一意 — 他のページと同じタイトルにしません

# Configure data views in Kibana

H1 が約50文字を超える場合は、フロントマターに navigation_title を追加します。

手順 3：導入段落を書く

導入段落は H1 の直後に配置し、2～4文で構成します。フロントマターの description を繰り返してはいけません。

ドキュメントの種類別

チュートリアル — 機能を定義し、その仕組みを説明し、チュートリアルで扱う内容を述べます。

Elasticsearch Query Language ({{esql}}) makes it easier to explore your data
in **Discover**. {{esql}} uses a piped syntax to filter, transform, and aggregate
data. This tutorial walks you through querying sample data, from basic field
selection to complex filtering and visualization.

ハウツー — 機能を定義し、その機能と価値を説明します。

Pattern analysis in **Discover** helps you find patterns in unstructured log
messages by performing categorization analysis on text fields. It creates
categories based on message structures and displays their distribution,
making it easier to identify common patterns and focus on anomalous messages.

リファレンス — 対象を定義し、その目的を述べます。

API keys provide secure, token-based authentication for applications accessing
{{product.elasticsearch}}. Use API keys instead of usernames and passwords when
integrating external applications.

解説 — コンテキストを示し、扱う概念を述べます。

{{product.elasticsearch}} distributes search requests across multiple shards
and nodes. Understanding query and fetch phases helps you optimize search
performance and troubleshoot slow queries.

概要 — 機能の概要と価値を示し、主な機能を説明します。

**Discover** is the primary tool for exploring your data in {{product.kibana}}.
Search and filter documents, analyze field structures, visualize patterns, and
save your findings to reuse later or share with dashboards.

主な原則

• フロントマターの description を繰り返さない
• 連続する2つの段落で同じ内容を繰り返さない
• 重要な情報を先に提示する
• 箇条書きの断片ではなく、完全な文を使用する
• 略語は初出時に正式名称を記載します：「Elasticsearch Query Language（{{esql}}）」

手順 4：「始める前に」セクションを追加する

次の条件をすべて満たす場合に限り、## 始める前に を追加します。

• 最初の50行に「始める前に」、要件、前提条件のセクションがない
• 概要ページではない
• 自明でない要件が少なくとも1つある

含める内容

• 名前付き機能に必要な、具体的な Kibana の権限レベル：All、Read、または None
• 自明でない前提条件（存在している必要があるデータ、外部システム、特別なライセンスなど）
• 機能に 9.0 を超えるバージョンが必要な場合に限り、バージョン要件

含めない内容

• 自明な前提条件（「ダッシュボードを編集する」における「既存のダッシュボード」など）
• 一般的なシステム要件（「Kibana へのアクセス」、「Elasticsearch が稼働していること」など）
• 本文に記載すべき手順の詳細
• 9.0 より前のバージョン番号

形式

説明的なアンカーを含む H2 を使用します。

## Before you begin [create-dashboard-before-you-begin]

To create dashboards, you need:

* [Data indexed into {{product.elasticsearch}}](/manage-data/ingest.md) and a [data view](../data-views.md).
* **All** privilege for the **Dashboard** feature in {{product.kibana}}.

H2 セクションが少なく、単純な要件が1つだけの場合は、段落を使用します。

You need the **All** privilege for the **Dashboard** feature.

手順 5：置換ルールを適用する

ハードコードされた製品名を Jinja2 の置換文字列に置き換えます。

• {{product.kibana}}、{{product.elasticsearch}}
• {{esql}}、{{data-source}}、{{data-sources}}
• {{ece}}、{{eck}}、{{ech}}

UI 要素（ボタン、アプリ、フィールドラベル）には太字を使用します。技術要素（コマンド、ファイルパス、設定）には monospace を使用します。

手順 6：Lint を実行する

編集したファイルに対して、編集直後に Vale を実行します。次のファイルに進む前に、冒頭セクションのエラーをすべて修正します。

vale <file>

事前チェック

ファイルを変更する前に、次の点を確認してください。

1. 最初の約20行にある重要または警告の注意書きは、絶対に変更、移動、書き換えないでください。その周囲の内容のみを編集してください。
2. 概要ページ（toc.yml に children: があるページ）には、「始める前に」セクションを追加しないでください。
3. 9.0 より前のバージョンへの言及は削除してください（これらのドキュメントは Stack 9 以降を対象としています）。9.0 より新しいバージョンのみ残してください。

品質チェックリスト

• ドキュメントの種類を正しく特定した
• H1 が固有で、具体的かつ検索しやすい（カスタムアンカーは不要。docs-builder が自動生成します）
• H1 が50文字を超える場合、navigation_title を追加した
• 冒頭の段落で frontmatter の説明を繰り返していない
• 冒頭で目的、価値、対象範囲を伝えている
• 適切な箇所に「始める前に」セクションを追加した（概要ページには追加しない）
• すべての置換を使用した（製品名をハードコードしていない）
• 頭字語は初出時に正式名称を記載した
• UI 要素には太字、技術要素には等幅フォントを使用した
• 9.0 より前のバージョンへの言及がない
• 重要または警告の注意書きを変更していない
• リンターを実行し、エラーを修正した