/kb-article

不明なプレースホルダーがある場合や、どのツールが接続されているかを確認する必要がある場合は、CONNECTORS.md を参照してください。

解決済みのサポートチケット、よくある質問、または文書化されたワークアラウンドから、公開準備完了のナレッジベース記事を作成します。セルフサービスと検索性のためにコンテンツを構成します。

使い方

/kb-article <解決済みの問題、チケット参照、またはトピックの説明>

例：

• /kb-article Okta による SSO 設定方法 — 先月 3 人の顧客がこれで解決した
• /kb-article チケット #4521 — 顧客が 1 万行を超えるデータをエクスポートできなかった
• /kb-article よくある質問：Webhook 通知の設定方法
• /kb-article 既知の問題：Safari 16 でダッシュボードのグラフが読み込まれない

ワークフロー

1. ソース資料の理解

入力を解析して以下を特定します：

• 問題は何か？ 元の問題、質問、またはエラー
• 解決策は何か？ 解決法、ワークアラウンド、または答え
• 誰に影響するか？ ユーザータイプ、プランレベル、または設定
• これはどのくらい一般的か？ 単発の問題か、繰り返す問題か
• どの記事タイプが適切か？ ハウツー、トラブルシューティング、FAQ、既知の問題、またはリファレンス（以下の記事タイプを参照）

チケット参照が提供されている場合は、完全なコンテキストを検索します：

• ~~サポートプラットフォーム: チケットスレッド、解決策、および内部メモを取得
• ~~ナレッジベース: 同様の記事が既に存在するかを確認（新規作成 vs. 更新）
• ~~プロジェクトトラッカー: 関連するバグまたは機能リクエストがあるかを確認

2. 記事を下書きする

以下の記事構造、フォーマット標準、および検索性のベストプラクティスを使用します：

• 選択した記事タイプ（ハウツー、トラブルシューティング、FAQ、既知の問題、またはリファレンス）のテンプレートに従う
• 検索性のベストプラクティスを適用：顧客向けの言葉で書いたタイトル、平易な文での開始文、正確なエラーメッセージ、一般的な同義語
• スキャン可能にする：ヘッダー、番号付きステップ、短い段落

3. 記事を生成する

メタデータとともにドラフトを提示します：

## KB Article Draft

**タイトル:** [記事のタイトル]
**タイプ:** [ハウツー / トラブルシューティング / FAQ / 既知の問題 / リファレンス]
**カテゴリー:** [製品エリアまたはトピック]
**タグ:** [検索可能なタグ]
**対象者:** [すべてのユーザー / 管理者 / 開発者 / 特定のプラン]

---

[以下の適切なテンプレートを使用した完全な記事コンテンツ]

---

### 公開時の注意事項
- **出典:** [チケット #、顧客との会話、または内部討議]
- **更新が必要な既存記事:** [このコンテンツと重複がある場合]
- **レビュー対象:** [技術的な正確性の確認が必要な場合は SME またはチーム]
- **推奨レビュー日:** [正確性を確認するために再確認する時期]

4. 次のステップを提案する

記事を生成した後：

• "ナレッジベースに同様の記事が既に存在するかを確認してほしい？"
• "異なる対象者向けに技術的な深さを調整すべき？"
• "関連記事を作成してほしい（例えば、このトラブルシューティングガイドに付随するハウツー）？"
• "追加の技術詳細を含む社内専用版を作成すべき？"

---

記事の構造とフォーマット標準

すべての記事に含まれるべき要素

すべての KB 記事には以下を含める必要があります：

1. タイトル: 明確で検索可能、結果または問題を説明（内部用語ではなく）
2. 概要: この記事が何をカバーしているか、誰を対象としているかを説明する 1 ～ 2 文
3. 本文: 記事タイプに適切な構造化コンテンツ
4. 関連記事: 関連する補足コンテンツへのリンク
5. メタデータ: カテゴリー、タグ、対象者、最終更新日

フォーマットルール

• ヘッダー（H2、H3）を使用してコンテンツをスキャン可能なセクションに分割
• 番号付きリストを順序のある手順に使用
• 箇条書きリストを非順序のアイテムに使用
• 太字を UI 要素名、重要な用語、および強調に使用
• コードブロックをコマンド、API 呼び出し、エラーメッセージ、設定値に使用
• テーブルを比較、オプション、またはリファレンスデータに使用
• コールアウト/注記を警告、ヒント、および重要な注意事項に使用
• 短い段落を保つ — 最大 2 ～ 4 文
• 1 セクションにつき 1 つのアイデア — セクションが 2 つのトピックをカバーしている場合は分割

検索可能性のための文章作成

顧客が見つけられなければ記事は役に立たません。すべての記事を検索のために最適化します：

タイトルのベストプラクティス

良いタイトル	悪いタイトル	理由
"Okta で SSO を設定する方法"	"SSO 設定"	具体的で、顧客が検索するツール名を含む
"修正：ダッシュボードが空白ページを表示する"	"ダッシュボードの問題"	顧客が経験する症状を含む
"API レート制限とクォータ"	"API 情報"	顧客が検索する特定の用語を含む
"エラー：データ インポート時に「接続が拒否されました」"	"インポートの問題"	正確なエラーメッセージを含む

キーワード最適化

• 正確なエラーメッセージを含める — 顧客はエラーテキストを検索にコピー貼り付けします
• 顧客の言葉を使用する、内部用語ではなく — "ログインできない" ではなく "認証失敗"ではなく
• 一般的な同義語を含める — "削除/削除"、"ダッシュボード/ホームページ"、"エクスポート/ダウンロード"
• 別の言い回しを追加する — 概要で同じ問題を異なる角度からアドレスします
• 製品エリアでタグ付けする — カテゴリーとタグが顧客が製品をどう考えるかと一致するようにします

開始文の公式

すべての記事を平易な言葉で問題またはタスクを言い直す文で開始します：

• ハウツー: "このガイドは [X を達成する] 方法を説明しています。"
• トラブルシューティング: "[症状] が表示されている場合、この記事はそれを修正する方法を説明しています。"
• FAQ: "[顧客の言葉での質問]？ ここに答えがあります。"
• 既知の問題: "一部のユーザーが [症状] を経験しています。ここではわかっていることとその回避方法を説明しています。"

記事タイプテンプレート

ハウツー記事

目的: タスクを実行するためのステップバイステップの指示。

構造:

# [タスクを達成] する方法

[概要 — このガイドがカバーしていることとそれを使用する場合]

## 前提条件
- [開始前に必要なもの]

## ステップ
### 1. [アクション]
[特定の詳細を含む指示]

### 2. [アクション]
[指示]

## 機能しているかどうかを確認する
[成功を確認する方法]

## 一般的な問題
- [問題]: [修正]

## 関連記事
- [リンク]

ベストプラクティス:

• 各ステップを動詞で開始する
• 特定のパスを含める：「設定 > 統合 > API キー に移動」
• 各ステップの後にユーザーが見るべきものを言及する（「緑色の確認バナーが表示されます」）
• ステップを自分でテストするか、最近のチケット解決で確認する

トラブルシューティング記事

目的: 特定の問題を診断および解決します。

構造:

# [問題の説明 — ユーザーが見るもの]

## 症状
- [ユーザーが観察することの説明]

## 原因
[これが起こる理由 — 簡潔で専門用語ではない説明]

## 解決策
### オプション 1：[主な修正]
[ステップ]

### オプション 2：[オプション 1 が機能しない場合の代替案]
[ステップ]

## 予防
[将来これを避ける方法]

## まだ問題がありますか？
[ヘルプを取得する方法]

ベストプラクティス:

• 原因ではなく症状で始める — 顧客は自分が見るものを検索します
• 可能な限り複数のソリューションを提供する（最も可能性の高い修正を最初に）
• 「まだ問題がありますか？」セクションを含める、サポートを指す
• 根本原因が複雑な場合は、顧客向けの説明を簡潔に保つ

FAQ 記事

目的: よくある質問への簡潔な答え。

構造:

# [質問 — 顧客の言葉で]

[直接的な答え — 1 ～ 3 文]

## 詳細
[追加のコンテキスト、細かい違い、または必要に応じて説明]

## 関連する質問
- [関連 FAQ へのリンク]
- [関連 FAQ へのリンク]

ベストプラクティス:

• 最初の文で質問に答える
• 簡潔に保つ — 答えにウォークスルーが必要な場合は、FAQ ではなくハウツーです
• 関連する FAQ をグループ化し、それらの間でリンクする

既知の問題記事

目的: 既知のバグまたは制限をワークアラウンドで文書化します。

構造:

# [既知の問題]: [簡潔な説明]

**ステータス:** [調査中 / ワークアラウンド利用可能 / 修正進行中 / 解決済み]
**影響を受けるもの:** [影響を受けるもの/人]
**最終更新:** [日付]

## 症状
[ユーザーが経験することの説明]

## ワークアラウンド
[問題を回避するためのステップ、または「利用可能なワークアラウンドはありません」]

## 修正のタイムライン
[予想される修正日または現在のステータス]

## 更新
- [日付]: [更新]

ベストプラクティス:

• ステータスを最新に保つ — 古い既知の問題記事ほど信頼を損なわせるものはありません
• 修正がリリースされたときに記事を更新し、解決済みとしてマーク
• 解決済みの場合、古い症状を検索しているお客様向けに 30 日間、記事をライブで保つ

レビューとメンテナンスの頻度

ナレッジベースはメンテナンスなしでは劣化します。このスケジュールに従います：

アクティビティ	頻度	担当者
新規記事レビュー	公開前	ピアレビュー + 技術コンテンツに関しては SME
正確性監査	四半期ごと	サポートチームがトップトラフィック記事をレビュー
古いコンテンツチェック	毎月	6 ヶ月以上更新されていない記事にフラグを付ける
既知の問題の更新	毎週	すべてのオープン既知の問題のステータスを更新
分析レビュー	毎月	どの記事が低い有用性評価または高いバウンスレートを持つかを確認
ギャップ分析	四半期ごと	KB 記事がないトップチケットトピックを特定

記事のライフサイクル

1. ドラフト: 作成完了、レビュー待ち
2. 公開: ライブで顧客が利用可能
3. 更新が必要: 修正に向けてフラグ（製品変更、フィードバック、または古さ）
4. アーカイブ: 関連性がなくなったが参考のために保存
5. 廃止: ナレッジベースから削除

更新 vs. 新規作成の時期

既存を更新する場合：

• 製品が変更されてステップを更新する必要がある
• 記事はほぼ正しいが詳細を欠いている
• フィードバックが示す顧客が特定のセクションで混乱している
• より良いワークアラウンドまたはソリューションが見つかった

新規作成する場合：

• 新しい機能または製品エリアにドキュメントが必要
• 解決済みのチケットがギャップを明らかにする — このトピックの記事が存在しない
• 既存の記事が多くのトピックをカバーしており、分割する必要がある
• 異なる対象者が同じ情報を異なる方法で説明する必要がある

リンクとカテゴリー分類体系

カテゴリー構造

顧客がどう考えるかと一致する階層に記事を整理します：

開始方法
├── アカウント設定
├── 初回構成
└── クイックスタートガイド

機能とハウツー
├── [機能エリア 1]
├── [機能エリア 2]
└── [機能エリア 3]

統合
├── [統合 1]
├── [統合 2]
└── API リファレンス

トラブルシューティング
├── 一般的なエラー
├── パフォーマンスの問題
└── 既知の問題

請求とアカウント
├── プランと料金
├── 請求に関する質問
└── アカウント管理

リンク作成のベストプラクティス

• トラブルシューティングからハウツーへリンク: "セットアップ手順については、[X を設定する方法] を参照"
• ハウツーからトラブルシューティングへリンク: "エラーが発生した場合は、[X のトラブルシューティング] を参照"
• FAQ から詳細記事へリンク: "完全なウォークスルーについては、[X ガイド] を参照"
• 既知の問題からワークアラウンドへリンク: 問題からソリューションへのチェーンを短く保つ
• KB 内で相対リンクを使用 — 絶対 URL よりも再構成に耐えやすい
• 循環リンクを避ける — A が B にリンクする場合、B は両方とも真に有用なエントリーポイントでない限り A に戻すべきではない

KB 作成のベストプラクティス

1. 答えを検索して不満を感じている顧客のために書く — 明確で、直接的で、役に立つ
2. すべての記事は顧客が入力するであろう言葉を使った検索で見つけられるべき
3. 記事をテストする — ステップを自分でフォローするか、トピックに慣れていない人にフォローしてもらう
4. 記事を焦点を絞ったままにする — 1 つの問題、1 つのソリューション。長くなりすぎる場合は分割
5. 積極的にメンテナンス — 間違った記事は記事がないことより悪い
6. 不足しているものを追跡 — KB 記事の対象になれたすべてのチケットはコンテンツギャップ
7. 影響を測定 — トラフィックが少ない記事またはチケットを削減しない記事は改善または廃止する必要がある