kb-authoring

記事の構成

必須コンポーネント

すべてのナレッジベース記事には、次の項目を含めます。

1. タイトル：成果または症状を中心にします。顧客が検索バーに入力する言葉で記述し、社内用語は使いません。
2. 概要：記事の内容と、どのような人に役立つかを平易な言葉で1～2文にまとめます。
3. 本文：記事の種類に応じて構成します（後述）。
4. 関連記事：関連するトピックを扱う記事へのリンクを掲載します。
5. メタデータ：カテゴリ、タグ、対象読者、最終更新日を記載します。

書式の基準

• 見出し（H2、H3）：読者が該当するセクションに移動しやすい、ひと目でわかる構成にします。
• 番号付きリスト：順序が重要な手順に使います。
• 箇条書き：順序のない項目や選択肢に使います。
• 太字：UIラベル、重要な用語、強調したい箇所に使います。
• コードブロック：コマンド、API ペイロード、エラー文字列、設定の断片に使います。
• 表：比較、選択肢の一覧、参照データに使います。
• コールアウト／注意書き：警告、ヒント、必読の注意事項に使います。
• 段落の長さ：2～4文までにします。長くて密度の高い段落は読者を遠ざけます。
• セクションの構成：1つのセクションでは1つの概念を扱います。複数の目的がある場合は、セクションを分けます。

記事を見つけやすくする

検索で見つけられない記事は、存在しないのと同じです。

タイトルの付け方

効果的なタイトル	効果の低いタイトル	理由
「Okta で SSO を設定する」	「SSO の設定」	顧客が検索する具体的なツール名を含んでいます
「修正方法：ダッシュボードに空白のページが表示される」	「ダッシュボードの問題」	顧客が経験する症状をそのまま表しています
「API のレート制限とクォータの参照情報」	「API の詳細」	ユーザーが検索する正確な用語を含んでいます
「エラー：データのインポート中に「Connection refused」が発生する」	「インポートエラー」	顧客が検索欄に貼り付けるエラー文字列を含んでいます

キーワード戦略

• 正確なエラーメッセージを含める：顧客はエラー文をそのまま検索欄に貼り付けることがよくあります。
• 顧客の言葉で書く：「認証の失敗」より「ログインできない」のほうが見つけてもらいやすくなります。
• 類義語を網羅する：「削除／取り除く」、「ホームページ／ダッシュボード」、「ダウンロード／エクスポート」などです。
• 異なる切り口を提示する：概要では、同じ問題を複数の視点から取り上げます。
• 製品の利用箇所に基づいてタグを付ける：カテゴリとタグは、エンジニアリング組織図ではなく、顧客の考え方を反映させます。

書き出しのパターン

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

• 手順型：「[X を達成する]には、以下の手順に従ってください。」
• 診断型：「[症状]が発生していますか？この記事では、解決方法を説明します。」
• 事実説明型：「[顧客が尋ねるような質問]？答えはこちらです。」
• アドバイス型：「[症状]が発生するユーザーもいます。何が起きているのか、回避方法をご紹介します。」

記事のテンプレート

手順型（ハウツー）記事

目標：タスクを最初から最後まで顧客に案内します。

# How to [accomplish task]

[Summary: what this covers and when you would need it]

## Before You Begin

- [Prerequisite 1]
- [Prerequisite 2]

## Instructions

### Step 1: [Action verb phrase]
[Precise instruction with path: Settings > Integrations > API Keys]

### Step 2: [Action verb phrase]
[Instruction, including what the user should see after completing this step]

## Confirm Success

[How to verify the task completed correctly]

## Troubleshooting

- [Potential hiccup]: [Resolution]

## See Also

- [Related article links]

ガイダンス：

• すべての手順を動詞で始めます。
• 「［設定］>［チーム］>［ロール］に移動します」のように、ナビゲーションの経路を明確に示します。
• 重要な確認ポイントでは、期待される結果を説明します。「緑色のバナーが表示されれば、保存は完了です。」
• 最近のチケットの解決内容を確認するか、自分で手順を実行して、説明が正しいことを確かめます。

診断型（トラブルシューティング）記事

目標：特定の不具合を顧客が特定し、解決できるよう支援します。

# [Problem statement matching what the user observes]

## What You See

- [Observable symptom 1]
- [Observable symptom 2]

## Why This Happens

[Concise, jargon-free explanation of the root cause]

## How to Fix It

### Fix 1: [Most likely resolution]
[Step-by-step instructions]

### Fix 2: [Alternate resolution if Fix 1 does not apply]
[Step-by-step instructions]

## Preventing Recurrence

[Configuration change or practice that avoids this in the future]

## Need More Help?

[How to contact support]

ガイダンス：

• まず症状ごとに構成します。顧客は症状を検索するためです。
• 最も可能性の高い解決方法を、代替案より先に提示します。
• サポート窓口につながる「さらにサポートが必要ですか？」の案内を必ず含めます。
• 技術的な原因が複雑な場合も、顧客向けの説明は簡潔にします。

クイックアンサー（FAQ）記事

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

# [Question in the customer's natural phrasing]

[Direct answer: 1-3 sentences]

## Additional Context

[Deeper explanation, edge cases, or nuance if needed]

## Related Questions

- [Link to related FAQ 1]
- [Link to related FAQ 2]

ガイドライン：

• 最初の文で質問に回答します。
• 回答に複数の手順を説明する必要がある場合は、FAQではなくハウツー記事にします。
• 関連するFAQ同士をリンクし、お客様が関連する質問についても自分で解決できるようにします。

既知の問題に関するお知らせ

目的：現在発生しているバグや制限事項について、現状と利用可能な回避策を記録します。

# [Known Issue]: [Brief description]

**Status:** [Investigating / Workaround Available / Fix Underway / Resolved]
**Who is affected:** [Scope]
**Last updated:** [Date]

## What Users Experience

[Description of the observable behavior]

## Workaround

[Step-by-step workaround, or "No workaround is currently available."]

## Resolution Timeline

[Estimated fix date or current engineering status]

## Change Log

- [Date]: [Update summary]

ガイドライン：

• ステータス欄は常に最新の状態に保ちます。古いステータス情報は、ほとんど何よりも早く信頼を損ないます。
• 修正がリリースされたらすぐに記事を更新し、「解決済み」とマークします。
• 過去の症状を引き続き検索するお客様が問題の解決を確認できるよう、解決済みのお知らせも少なくとも30日間公開しておきます。

コンテンツのライフサイクルとメンテナンス

ナレッジベースは、継続的に管理しなければ劣化します。次の頻度で運用してください。

活動	頻度	担当者
新規記事のピアレビュー	公開前	作成者＋分野の専門家
アクセス数の多い記事の正確性監査	四半期ごと	サポートチーム
古いコンテンツの検出	月次	6か月以上更新されていない記事にフラグを付ける
既知の問題のステータス更新	週次	未解決のお知らせをすべて更新する
有効性のレビュー	月次	役立ち度の評価、直帰率、検索からクリックへの比率を確認する
カバレッジギャップ分析	四半期ごと	対応するKB記事がない、問い合わせの主な原因を特定する

記事の状態

1. 下書き：作成済みで、レビュー待ち
2. 公開中：公開され、お客様がアクセス可能
3. 要確認：製品の変更、ユーザーからのフィードバック、または経過期間を理由に改訂対象としてマークされている
4. アーカイブ済み：お客様向けの表示からは削除されているが、社内の参考情報として保持されている
5. 削除済み：ナレッジベースから完全に削除されている

更新するか新規作成するかの判断基準

既存の記事を改訂する場合：

• 製品の更新によって手順が変わったものの、トピックは同じ場合
• 記事の基本的な内容は適切だが、詳細が不足している場合
• お客様からのフィードバックで、わかりにくい箇所が指摘された場合
• より優れた回避策や解決策が見つかった場合

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

• 新機能や製品の領域にドキュメントがない場合
• 解決済みの問い合わせから、KBのカバレッジがまったくないトピックが判明した場合
• 既存の記事が扱いきれないほど長くなり、分割が必要な場合
• 同じ情報を異なる形で提示する必要がある、別の対象者がいる場合

分類と相互リンク

推奨カテゴリ階層

組織の構造ではなく、お客様のナビゲーション方法に合わせてナレッジベースを構成します。

Getting Started
  Account creation and setup
  Initial configuration
  Quickstart walkthroughs

Product Capabilities
  [Capability area A]
  [Capability area B]
  [Capability area C]

Integrations
  [Integration A]
  [Integration B]
  API reference

Problem Solving
  Frequent errors
  Performance and reliability
  Active known issues

Billing and Account Management
  Plans and pricing
  Payment and invoicing
  Account settings

相互リンクの原則

• 診断から手順へ：「セットアップ手順については、[X の設定方法]を参照してください。」
• 手順から診断へ：「エラーが発生していますか？[X のトラブルシューティング]を参照してください。」
• FAQから詳細記事へ：「詳しい手順については、[X のガイド]を参照してください。」
• お知らせから回避策へ：問題の特定から解決までに必要なクリック数を最小限にします。
• 相対リンクを優先する：絶対URLよりも、再編成後も使える可能性が高くなります。
• 不必要な相互リンクを避ける：AからB、BからAへのリンクは、両方が実際に入口として機能する場合に限り適切です。

基本原則

1. 検索中で困っているお客様に向けて、率直かつ具体的に、すぐ役立つ内容を書きます。
2. すべての記事は、実際のお客様が入力しそうな言葉で見つけられる必要があります。
3. 内容を検証します。自分で手順を実行するか、そのトピックに詳しくない人に試してもらいます。
4. 焦点を絞ります。1つの記事で扱うのは1つの問題と1つの解決策です。範囲が広がりすぎたら分割します。
5. 積極的に手入れします。古い記事は、記事がないことよりも有害です。
6. ギャップを追跡します。記事があれば問い合わせを回避できたはずの案件はすべて、コンテンツ作成の機会です。
7. 成果を測定します。アクセス数が少ない、評価が低い、問い合わせ削減への効果がない記事は、改訂または廃止が必要です。