knowledge-base-article-writing

ナレッジベース記事の執筆

お客様が明確な自己解決方法を見つけられるよう、洗練されたヘルプセンター記事やFAQ項目を作成し、サポートチケットの発生を抑えます。このスキルでは、サポートチケットの傾向、製品の変更、よくある質問を、読みやすさ、検索性、一覧性に優れた構成の記事にまとめます。その際、手順ガイド、トラブルシューティングのフロー、リファレンス資料に関するドキュメント作成のベストプラクティスに従います。

ワークフロー

1. サポートデータからトピックを特定する — サポートチケットの傾向、検索分析（お客様が検索しても見つけられていない情報）、CSMからのフィードバックを調べ、最も影響の大きいトピックを見つけます。チケット数（質問クラスターの上位10件を扱う記事が、最も多くのチケットを抑制します）、トピックの複雑さ（複雑なトピックほど、文書化されたガイドが役立ちます）、新しさ（新機能や最近の変更は、すぐにドキュメントが必要です）に基づいて優先順位を付けます。

2. 解決方法を調査する — エンジニアリングドキュメント、社内Wiki、製品仕様、専門家から、信頼できる回答を集めます。製品上でワークフローを最初から最後まで自分で試し、正確性を確認します。現在の製品バージョンに表示されるUIテキスト、ボタンラベル、ナビゲーション経路を正確に記録します。前提条件、必要な権限、プランによる制限も書き留めます。

3. 記事を構成する — 一貫したテンプレートに従います。タイトル（行動を促し、お客様の検索語句に合致するもの）、概要（ざっと読んで答えがわかる1～2文）、前提条件（開始前に読者が用意するもの）、手順（各ステップにつき1つの操作を番号付きで示し、期待される結果も記載）、トラブルシューティング（よくあるエラーとその解決方法）、関連記事（関連トピックへのリンク）。階層は浅く保ち、主要セクションにはH2を使用し、H3は必要な場合に限ります。

4. 視覚資料とコード例を追加する — UI中心のワークフローにはスクリーンショット（手順に対応した番号付きの注釈を付けます）、APIやCLIのワークフローにはコードスニペット（言語タグ、コピー用ボタン、期待される出力を付けます）、アーキテクチャやフローの説明には図を含めます。すべての画像に代替テキストを付けます。すべてのコードブロックはテストし、実行できることを確認します。

5. 検索向けに最適化する — お客様が実際に使う正確な表現（検索分析で確認します）を使ってタイトルを書きます。最初の文で重要なキーワードを前方に配置します。カテゴリ、製品領域、プラン階層のメタデータタグを追加します。よく使われる別の表現は、「別名」行または記事のメタデータに含めます。URLは簡潔で、人にとってわかりやすいものにします。

6. 正確性と明瞭さをレビューする — 専門家に技術的な正確性を確認してもらいます。読解レベルが8年生相当になるよう、読みやすさを確認します。事前知識のない人でも各手順を実行して検証できることを確認します。スクリーンショットが現在のUIと一致しているか確認します。すべてのリンクを検証します。確認期限を設定します（通常は90日後、またはトピックに影響する次の製品リリース時）。

使用方法

記事のトピック、対象読者、含めるべき具体的な情報を説明してください。エージェントが、公開できる状態の記事を完成させます。

Write a help center article for "How to set up SSO with SAML." Target audience
is IT admins. Our product supports Okta, Azure AD, and OneLogin. Include
troubleshooting for common SAML errors.

例

例1：ハウツー記事 — SAML による SSO の設定

入力： IT 管理者向けの SSO／SAML 設定ガイド。

出力：

---

SAML によるシングルサインオン（SSO）の設定方法

SAML ベースの SSO を有効にすると、チームは会社のアイデンティティプロバイダーを使ってサインインできます。対応プロバイダー：Okta、Azure AD、OneLogin。

前提条件

• アカウントの管理者ロール（Settings → Team → Roles で、自分の名前の横に「Admin」と表示されていること）
• アイデンティティプロバイダーの管理者コンソールへのアクセス権
• アカウントが Enterprise プランであること

手順

1. Settings → Security → Single Sign-On に移動し、Configure SSO をクリックします。

   [スクリーンショット：Security タブがハイライトされ、SSO セクションが表示された Settings ページ]

2. ドロップダウンからアイデンティティプロバイダーを選択します：Okta、Azure AD、または OneLogin。

3. 画面に表示されている値をコピーします。アイデンティティプロバイダーで使用します：

   • ACS URL： https://app.example.com/auth/saml/callback
   • Entity ID： https://app.example.com/saml/metadata
   • RelayState： カスタムのランディングページを使用する場合を除き、空欄のままにします

4. アイデンティティプロバイダーの管理者コンソールで、手順3の値を使って新しい SAML アプリケーションを作成します。

   Okta： Applications → Create App Integration → SAML 2.0 → ACS URL と Entity ID を貼り付けます。

   Azure AD： Enterprise Applications → New Application → Create your own → SAML → Basic SAML Configuration → 値を貼り付けます。

   OneLogin： Applications → Add App → SAML Custom Connector → Configuration → 値を貼り付けます。

5. アイデンティティプロバイダーから Federation Metadata XML ファイルをダウンロードし、SSO 設定ページにアップロードします。

6. 必須の属性マッピングを設定します：

   email    → user.email       (Required)
   firstName → user.firstName  (Required)
   lastName  → user.lastName   (Required)
   role      → user.role       (Optional — maps to app roles)
   

7. Test Connection をクリックします。新しいブラウザータブが開きます。アイデンティティプロバイダーの認証情報でサインインします。成功すると、「SSO connection verified.」と表示されます。

8. Enforce SSO を切り替えて、すべてのチームメンバーにアイデンティティプロバイダー経由でのサインインを必須にします。24時間の猶予期間後、SSO 以外でのログインは無効になります。

トラブルシューティング

エラー	原因	対処方法
"SAML response signature invalid"	メタデータ XML が古い、または別のアプリのものです	IdP からメタデータ XML を再ダウンロードし、再アップロードします
"User not found"	SAML アサーション内のメールアドレスが、どのアカウントのメールアドレスとも一致しません	IdP のメール属性マッピングで、ユーザーのメインのメールアドレスが送信されることを確認します
"Clock skew detected"	IdP と当社サービスのサーバー時刻の差が5分を超えています	IdP サーバーの NTP が同期されていることを確認します。5分までの時刻差を許容します
"Audience mismatch"	IdP の Entity ID が手順3の値と一致しません	Settings → SSO から Entity ID を正確にコピーします。末尾のスラッシュも重要です
テストは成功するが、ユーザーがログインできない	Enforce SSO がオフになっているか、ユーザーが誤ったログイン URL を使っています	Settings → SSO の SSO ログイン URL をチームに共有し、Enforce SSO を有効にします

関連記事

• チームのロールと権限の管理
• SCIM ユーザープロビジョニングの設定
• 多要素認証の設定

---

例 2：FAQ 項目 — 請求に関する質問

入力： プランの変更、請求書、返金を扱う、よくある請求に関するFAQです。

出力：

---

請求に関するFAQ

プラン、請求書、支払い、返金について、よく寄せられる質問への回答です。

プランをアップグレードまたはダウングレードするにはどうすればよいですか？

Settings → Billing → Plan に移動し、Change Plan をクリックします。新しいプランを選択して確定してください。アップグレードは直ちに適用され、請求サイクルの残り期間分が日割りで請求されます。ダウングレードは次の請求サイクルの開始時に適用されます。それまでは、現在のプランの機能を引き続き利用できます。

請求書はどこで確認できますか？

すべての請求書は Settings → Billing → Invoice History で確認できます。請求書をクリックすると、表示またはPDFのダウンロードができます。請求書は、各請求から24時間以内に登録済みの請求先連絡先にもメールで送信されます。

支払い方法を更新するにはどうすればよいですか？

Settings → Billing → Payment Method に移動し、Update をクリックします。Visa、Mastercard、American Express、ACH銀行振込（年間プランのみ）をご利用いただけます。新しい支払い方法は、今後のすべてのお支払いに使用されます。

返金を受けられますか？

ご満足いただけない場合、請求から14日以内であれば全額返金いたします。14日を過ぎた場合は、今後の請求に充当する日割りのクレジットを発行します。返金を希望する場合は、アカウントのメールアドレスと請求書番号を [email protected] までメールでお知らせください。返金処理には5～7営業日かかります。

支払いに失敗した場合はどうなりますか？

支払いに失敗した場合、1日目、3日目、7日目に再試行します。試行が失敗するたびに、メールで通知します。14日以内に支払いが解決されない場合、アカウントは無料プランにダウングレードされます。データは90日間保持されます。いつでもアップグレードして、すべての機能へのアクセスを復元できます。

年間請求の割引はありますか？

はい。有料プランはすべて、月払いと比べて年払いにすると20％お得になります。Settings → Billing → Plan からいつでも年払いに切り替えられます。「Annual」を選択すると、残りの月払い期間分のクレジットが日割りで適用され、割引が直ちに反映されます。

関連記事

• 請求書の明細項目について
• ACH銀行振込による支払いの設定
• 複数の請求アカウントの管理

---

ベストプラクティス

• タイトルは、顧客が検索する際の言い回しに合わせて、質問形式または行動を示すフレーズにします。「SSO Configuration Guide」よりも「How to set up SSO」のほうが適しています。顧客は自然な言葉で検索するためです。
• 1つの記事につき1つのトピックを扱います。記事が異なる2つのワークフローを扱っている場合は、分割してください。「データをエクスポート」で検索した顧客が、「データをインポート」も扱うページにたどり着かないようにします。たとえ関連しているように思えても同様です。
• すべての記事は、質問に直接答える1文の要約から始めます。顧客は記事を精読するのではなく、ざっと目を通します。答えが最初の行にあれば、先を読まなくても役立つ情報を得られます。
• UIのラベルと完全に一致する、一貫した用語を使います。ボタンの表示が「Configure」なら、記事でも「Set Up」ではなく「Configure」と記載してください。ドキュメントとUIの不一致は混乱を招き、信頼を損ないます。
• すべての記事に「最終確認日」を記載し、記事が扱う製品領域について変更履歴に更新があった際に、自動でアラートを送信する仕組みを構築します。
• 次の2つの指標を使って記事の有効性を追跡します。検索から閲覧への率（顧客は記事を見つけられているか）と、問い合わせ抑止率（閲覧から30分以内に顧客がチケットを作成したか）です。

エッジケース

• 執筆から公開までの間に製品 UI が変更される場合 — 記事の本文を確定してから、最後にスクリーンショットを撮影してください。古いスクリーンショットを監査時に特定しやすくするため、画像の代替テキストに製品のバージョン番号を含めてください。
• 特定のプランでのみ利用できる機能 — 冒頭に「この機能は Pro プランと Enterprise プランでご利用いただけます。」というコールアウトバナーを追加してください。読者が時間をかけた後の手順 4 で、プランの利用制限を初めて説明することは避けてください。
• 複数の言語に対応するナレッジベース — まず英語で正式版の記事を作成してから、ローカライズしてください。機械翻訳した内容を人間のレビューなしで公開しないでください。技術用語と UI ラベルは、ローカライズされた製品インターフェースに合わせる必要があります。
• 非推奨の機能 — 非推奨の機能に関する記事を削除しないでください。提供終了日を記載した非推奨バナーを追加し、代替記事へのリンクを設定してください。従来のプランをご利用のお客様には、古いドキュメントが引き続き必要な場合があります。
• 複数の情報源で情報が食い違っている場合 — 社内ドキュメントの内容と製品の実際の動作が異なる場合は、製品の動作を正とします。製品でテストし、実際の動作を記録してください。動作に誤りがある場合は、バグを報告してください。