kb-article

/kb-article

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

解決済みのサポート課題、よくある質問、または文書化された回避策から、公開可能なナレッジベース記事を作成します。検索性とセルフサービスを考慮して内容を構成します。

使用方法

/kb-article <resolved issue, ticket reference, or topic description>

例：

• /kb-article How to configure SSO with Okta — resolved this for 3 customers last month
• /kb-article Ticket #4521 — customer couldn't export data over 10k rows
• /kb-article Common question: how to set up webhook notifications
• /kb-article Known issue: dashboard charts not loading on Safari 16

ワークフロー

1. 元資料を把握する

入力を解析し、以下を特定します。

• 問題は何でしたか？ 元の課題、質問、またはエラー
• 解決策は何でしたか？ 解決方法、回避策、または回答
• 誰に影響しますか？ ユーザーの種類、プランのレベル、または設定
• どれくらいよく発生しますか？ 単発の問題か、繰り返し発生する問題か
• 最適な記事の種類は何ですか？ ハウツー、トラブルシューティング、FAQ、既知の問題、またはリファレンス（以下の記事の種類を参照）

チケットの参照情報がある場合は、詳しい背景を確認します。

• ~~support platform：チケットのスレッド、解決方法、内部メモを取得します
• ~~knowledge base：類似の記事がすでに存在するか確認します（更新するか、新規作成するか）
• ~~project tracker：関連するバグや機能リクエストがあるか確認します

2. 記事を下書きする

以下の構成、書式の基準、検索性に関するベストプラクティスに従います。

• 選択した記事の種類（ハウツー、トラブルシューティング、FAQ、既知の問題、またはリファレンス）のテンプレートに従います
• 検索性に関するベストプラクティスを適用します。顧客が使う言葉を含むタイトル、平易な言葉での導入文、正確なエラーメッセージ、一般的な同義語を使用します
• スキャンしやすい形式にします。見出し、番号付き手順、短い段落を使用します

3. 記事を生成する

メタデータを付けて下書きを提示します。

## KB Article Draft

**Title:** [Article title]
**Type:** [How-to / Troubleshooting / FAQ / Known Issue / Reference]
**Category:** [Product area or topic]
**Tags:** [Searchable tags]
**Audience:** [All users / Admins / Developers / Specific plan]

---

[Full article content — using the appropriate template below]

---

### Publishing Notes
- **Source:** [Ticket #, customer conversation, or internal discussion]
- **Existing articles to update:** [If this overlaps with existing content]
- **Review needed from:** [SME or team if technical accuracy needs verification]
- **Suggested review date:** [When to revisit for accuracy]

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

記事の生成後：

• 「~~knowledge base に類似の記事がすでにあるか確認しましょうか？」
• 「別の読者層に合わせて技術的な詳しさを調整しますか？」
• 「関連する記事（例：このトラブルシューティングガイドに合わせたハウツー記事）も作成しましょうか？」
• 「技術的な詳細を追加した社内限定版を作成しますか？」

---

記事の構成と書式の基準

すべての記事に含める要素

すべての KB 記事に、次の要素を含めます。

1. タイトル：明確で検索しやすく、結果または問題を説明する（社内用語は避ける）
2. 概要：記事の内容と対象読者を説明する1～2文
3. 本文：記事の種類に合った構成のコンテンツ
4. 関連記事：関連する補足コンテンツへのリンク
5. メタデータ：カテゴリー、タグ、対象読者、最終更新日

書式ルール

• スキャンしやすいセクションに分けるため、**見出し（H2、H3）**を使用します
• 順番に従う手順には番号付きリストを使用します
• 順不同の項目には箇条書きを使用します
• UI 要素名、重要な用語、強調箇所には太字を使用します
• コマンド、API 呼び出し、エラーメッセージ、設定値にはコードブロックを使用します
• 比較、選択肢、参照データには表を使用します
• 警告、ヒント、重要な注意事項にはコールアウトや注記を使用します
• 段落は短く保ちます — 最大2～4文にします
• 1つのセクションにつき1つのアイデア — 1つのセクションで2つのトピックを扱う場合は、分割します

検索されやすい記事の書き方

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

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

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

キーワードの最適化

• 正確なエラーメッセージを含める — 顧客はエラーのテキストをコピーして検索に貼り付けます
• 社内用語ではなく、顧客の言葉を使う — 「ログインできない」であって、「認証エラー」ではありません
• 一般的な同義語を含める — 「削除／取り除く」、「ダッシュボード／ホームページ」、「エクスポート／ダウンロード」
• 別の言い回しを追加する — 概要で、同じ問題を異なる切り口から説明します
• 製品分野のタグを付ける — カテゴリーとタグが、顧客の製品に対する考え方と一致していることを確認します

冒頭の文の形式

すべての記事は、問題やタスクを平易な言葉で言い換える文から始めます。

• ハウツー：「このガイドでは、[X を達成する方法]を説明します。」
• トラブルシューティング：「[症状]が発生している場合、この記事ではその解決方法を説明します。」
• FAQ：「[顧客の言葉による質問]？答えはこちらです。」
• 既知の問題：「一部のユーザーで[症状]が発生しています。現状と回避策について説明します。」

記事タイプ別テンプレート

ハウツー記事

目的：タスクを達成するための手順を説明します。

構成：

# How to [accomplish task]

[Overview — what this guide covers and when you'd use it]

## Prerequisites
- [What's needed before starting]

## Steps
### 1. [Action]
[Instruction with specific details]

### 2. [Action]
[Instruction]

## Verify It Worked
[How to confirm success]

## Common Issues
- [Issue]: [Fix]

## Related Articles
- [Links]

ベストプラクティス：

• 各手順を動詞で始めます
• 具体的なパスを記載します：「Settings > Integrations > API Keys に移動します」
• 各手順の後にユーザーに表示される内容を記載します（「緑色の確認バナーが表示されます」）
• 自分で手順を試すか、最近のチケット解決内容で確認します

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

目的：特定の問題を診断して解決します。

構成：

# [Problem description — what the user sees]

## Symptoms
- [What the user observes]

## Cause
[Why this happens — brief, non-jargon explanation]

## Solution
### Option 1: [Primary fix]
[Steps]

### Option 2: [Alternative if Option 1 doesn't work]
[Steps]

## Prevention
[How to avoid this in the future]

## Still Having Issues?
[How to get help]

ベストプラクティス：

• 原因ではなく症状から説明します — 顧客は目にしている現象を検索します
• 可能な場合は複数の解決策を示します（最も可能性の高い解決策を最初に示します）
• サポートへの問い合わせを案内する「まだ問題が解決しない場合」セクションを含めます
• 根本原因が複雑な場合は、顧客向けの説明を簡潔にします

FAQ記事

目的：よくある質問にすばやく回答します。

構成：

# [Question — in the customer's words]

[Direct answer — 1-3 sentences]

## Details
[Additional context, nuance, or explanation if needed]

## Related Questions
- [Link to related FAQ]
- [Link to related FAQ]

ベストプラクティス：

• 最初の文で質問に回答します
• 簡潔にまとめます — 回答に手順の説明が必要なら、FAQではなくハウツー記事です
• 関連するFAQをまとめ、相互にリンクします

既知の問題に関する記事

目的：既知のバグや制限事項とその回避策を記録します。

構成：

# [Known Issue]: [Brief description]

**Status:** [Investigating / Workaround Available / Fix In Progress / Resolved]
**Affected:** [Who/what is affected]
**Last updated:** [Date]

## Symptoms
[What users experience]

## Workaround
[Steps to work around the issue, or "No workaround available"]

## Fix Timeline
[Expected fix date or current status]

## Updates
- [Date]: [Update]

ベストプラクティス：

• ステータスを最新に保ちます — 古いままの既知の問題の記事ほど、信頼を損なうものはありません
• 修正がリリースされたら記事を更新し、解決済みとしてマークします
• 解決済みの場合も、以前の症状を検索している顧客のために、記事を30日間公開したままにします

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

ナレッジベースはメンテナンスしなければ古くなります。次のスケジュールに従ってください。

活動	頻度	担当者
新しい記事のレビュー	公開前	ピアレビュー ＋ 技術的な内容については SME
正確性の監査	四半期ごと	サポートチームがアクセス数の多い記事をレビュー
古いコンテンツの確認	毎月	6か月以上更新されていない記事にフラグを付ける
既知の問題の更新	毎週	すべての未解決の既知の問題のステータスを更新
分析のレビュー	毎月	役立ち度の評価が低い、または直帰率が高い記事を確認
ギャップ分析	四半期ごと	ナレッジベースの記事がない、チケットの主要なトピックを特定

記事のライフサイクル

1. 下書き：作成済みで、レビューが必要
2. 公開済み：公開され、顧客が利用可能
3. 更新が必要：改訂のためにフラグが付けられている（製品の変更、フィードバック、または経過年数）
4. アーカイブ済み：関連性はなくなったものの、参照用に保存されている
5. 廃止済み：ナレッジベースから削除されている

更新するか、新規作成するか

既存の記事を更新する場合：

• 製品が変更され、手順を更新する必要がある
• 記事の大部分は正しいが、詳細が不足している
• 特定のセクションで顧客が混乱しているというフィードバックがある
• より良い回避策や解決策が見つかった

新しい記事を作成する場合：

• 新機能や製品分野のドキュメントが必要
• 解決済みのチケットからギャップが判明した — このトピックの記事が存在しない
• 既存の記事で扱うトピックが多すぎるため、分割する必要がある
• 別の対象者向けに、同じ情報を異なる方法で説明する必要がある

リンクと分類のタクソノミー

カテゴリー構造

顧客の考え方に合った階層に記事を整理します。

Getting Started
├── Account setup
├── First-time configuration
└── Quick start guides

Features & How-tos
├── [Feature area 1]
├── [Feature area 2]
└── [Feature area 3]

Integrations
├── [Integration 1]
├── [Integration 2]
└── API reference

Troubleshooting
├── Common errors
├── Performance issues
└── Known issues

Billing & Account
├── Plans and pricing
├── Billing questions
└── Account management

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

• トラブルシューティングからハウツー記事にリンクする：「設定手順については、[X の設定方法] をご覧ください」
• ハウツー記事からトラブルシューティングにリンクする：「エラーが発生した場合は、[X のトラブルシューティング] をご覧ください」
• FAQ から詳細記事にリンクする：「詳しい手順については、[X のガイド] をご覧ください」
• 既知の問題から回避策にリンクする：問題から解決策までの流れを短く保ちます
• KB 内では相対リンクを使用する — 絶対 URL よりも、構成変更後もリンク切れしにくくなります
• 循環リンクを避ける — A から B にリンクする場合、両方が本当に有用な入口でない限り、B から A にリンクしないでください

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

1. 不満を抱えて答えを探している顧客に向けて書きます。明確で、直接的で、役に立つ内容にしてください
2. すべての記事が、顧客が入力しそうな言葉で検索して見つかるようにします
3. 記事をテストします。自分で手順を実行するか、内容に詳しくない人に実行してもらいます
4. 記事の焦点を絞ります。1 つの問題に対して 1 つの解決策を示します。記事が長くなりすぎる場合は分割します
5. 積極的にメンテナンスします。誤った記事は、記事がないよりも悪いものです
6. 不足している内容を追跡します。KB 記事にできる問い合わせはすべて、コンテンツの不足を示しています
7. 効果を測定します。アクセスがない記事や問い合わせの削減につながらない記事は、改善するか廃止する必要があります