support-docs

サポートドキュメント

使用するタイミング

創業者やチームメンバーが、ユーザーが自力で問題を解決できるよう支援する、顧客向けドキュメントを作成する必要がある場合に有効化します。「ヘルプセンターの記事を書いて」「FAQを作成して」「APIをドキュメント化して」「トラブルシューティングガイドを書いて」「スタートガイドを作って」「サポートチケットで同じ質問が何度も寄せられる」といった依頼が該当します。

必要なコンテキスト

• startup-contextから： 製品の種類、対象ユーザーの技術レベル、既存のドキュメント（あれば）、サポートチケットの主なカテゴリ、ドキュメントのホスティングに使用しているツール（例：Notion、GitBook、Zendesk、ReadMe）。
• ユーザーから： ドキュメント化する具体的なトピック、対象読者（エンドユーザー、管理者、開発者）、ユーザーの技術的な習熟度、よくある失敗パターンや混乱しやすい点、新規記事か既存コンテンツの更新か。

ワークフロー

1. ドキュメントの種類を特定する — ヘルプセンター記事、FAQ、トラブルシューティングガイド、APIリファレンス、スタートガイドのうち、どのテンプレートが適切か判断します。それぞれ、ユーザーの異なる目的に応えるものです。
2. ユーザーがドキュメントにたどり着く経路を定義する — どのようにこのドキュメントを見つけるのでしょうか？検索クエリ、エラーメッセージ、サポート担当者からのリンク、アプリ内のヘルプボタンでしょうか？これによってタイトルと冒頭の一文が決まります。
3. 問題と解決策の形式で書く — ユーザーの問題（ユーザー自身の言葉で）を最初に示し、その後に解決策を提示します。製品アーキテクチャの説明から始めてはいけません。
4. 段階的に情報を開示する — 最も一般的な答えを最初に配置します。まれなケース、高度なオプション、技術的な詳細は、折りたたみ可能なセクションや記事の後半に配置します。
5. 検索性を高める要素を追加する — 正確なエラーメッセージ、機能名、ユーザーが検索する口語的な表現を含めます。重要な語句は自然な形で繰り返します。
6. 「午前3時ルール」でテストする — ワークフローが壊れて困っている午前3時のユーザーになったつもりで記事を読みます。2分以内に解決策にたどり着けるでしょうか？できない場合は構成を見直します。
7. 関連する記事にリンクする — ユーザーがセルフサービスの流れを続けられるよう、記事の末尾に「関連情報」または「次のステップ」のリンクを追加します。

出力形式

以下の5つのテンプレートのいずれかに従ったMarkdownドキュメント。すべてのサポートドキュメントは、30秒以内に内容を把握でき、2分以内に問題を解決できるものである必要があります。

テンプレート1：ヘルプセンター記事

# [Action-oriented title: "How to X" or "Setting up Y"]

[One sentence describing what this article helps you do.]

## Before You Start
- Prerequisites or permissions needed

## Steps
1. Action step with specific UI path (Settings > Integrations > Slack)
2. Next action step
   > **Note:** Important callout for common mistakes

## Frequently Asked Questions
**Q: Common question about this feature?**
A: Direct answer.

## Still Need Help?
Contact support at [link] or chat with us in-app.

テンプレート2：トラブルシューティングガイド

# Troubleshooting: [Problem in user's words]

## Symptoms
What the user sees when this problem occurs (exact error messages in code blocks).

## Quick Fix
The solution that works 80% of the time. Put this first.

## If That Didn't Work
### Cause 1: [Most common cause]
How to diagnose → How to fix

### Cause 2: [Second most common]
How to diagnose → How to fix

## Collect Information for Support
If none of the above worked, gather these details before contacting support:
- [Specific data point 1]
- [Specific data point 2]

テンプレート3：FAQページ

質問をカテゴリ別（はじめに、よくある問題、請求）にまとめます。回答はそれぞれ1～3文とし、詳しい説明が必要な場合は記事全体へのリンクを付けます。

テンプレート4：APIドキュメント

構成：エンドポイントとメソッド、認証、リクエストパラメーター（名前／型／必須／説明の表）、リクエスト例（動作するcurl）、レスポンス例（成功時とすべてのエラーコード）、レート制限。すべてのコードスニペットは、コピーして貼り付ければ動作するものである必要があります。

テンプレート5：スタートガイド

構成：得られる成果と所要時間を示す歓迎の一文、順番に進める3～5個の手順（各手順で実施する操作とその重要性を説明）、確認のタイミング（「Xが表示されているはずです」）、より詳しい機能への「次のステップ」リンク。

フレームワークとベストプラクティス

問題・解決策・確認のパターン

すべてのサポートドキュメントで、次の流れに従います。

1. 問題： ユーザーが何をしようとしているのか、何がうまくいかなかったのかを（社内用語ではなく、ユーザーの言葉を使って）説明します。
2. 解決策： 修正方法や手順を、順番に、正確なUIの経路と各手順で期待される結果とともに示します。
3. 確認： 正しく機能したことを確認する方法をユーザーに伝えます。「YページにXが表示されているはずです。」

検索性の原則

• タイトルを検索クエリに一致させます。「CSV へのデータのエクスポート方法」とし、「データエクスポート機能の概要」とはしません。
• **エラーメッセージをそのまま記載します。**ユーザーに Error 403: Insufficient permissions と表示される場合は、トラブルシューティングガイドにその文字列を正確に記載します。
• 技術用語と一般的な用語の両方を使います。「シングルサインオン（SSO）」と記載すると、「SSO」と「シングルサインオン」のどちらで検索しても記事が見つかります。
• **回答を最初に提示します。**解決策を最初の 100 語以内に記載します。多くのユーザーは最後までスクロールしません。

段階的な情報開示のルール

• **レベル 1（表示）：**ユーザーの 80% に有効な回答。
• **レベル 2（展開可能）：**例外的なケース、高度な設定、プラットフォーム固有の違い。
• **レベル 3（リンク先）：**技術的な詳細、アーキテクチャの説明、API リファレンス全体。
• 基本的なユーザーが簡単な回答を得るために、高度な内容を読む必要がないようにします。

文体とメンテナンス

• 二人称、現在形を使います。「保存をクリックします」とし、「保存をクリックすることになります」とはしません。「できます」とし、「ユーザーはできます」とはしません。
• 具体的な UI のパスを示します。「設定 > チーム > 権限に移動します」とし、「チームの設定に移動します」とはしません。
• **操作を示してから説明します。**最初に操作を示し、次に背景を説明します。ユーザーはまず問題を解決し、その後で理解したいと考えています。
• **用語を統一します。**UI で「Workspace」と表示されている場合、ドキュメントで「Organization」と呼ぶことは避けます。
• **すべての記事にタグと日付を付けます。**古いドキュメントは、ドキュメントがないよりも悪影響を及ぼします。製品のリリースごとに見直します。
• **問い合わせ削減率を追跡します。**ヘルプ記事を公開しても、そのトピックに関するサポートチケットが減らない場合は、記事を書き直します。
• フィードバックウィジェットを追加します。「役に立ちましたか？ はい／いいえ」—「いいえ」の回答をドキュメントの担当者に送ります。

関連スキル

• process-docs — サポートのトピックで、顧客向けドキュメントだけでは解決できない例外的なケースやエスカレーションに対応するため、社内 SOP が必要な場合に連携します。
• onboarding-flow — 新規ユーザーのオンボーディング体験の一部となる、利用開始ガイドを作成する場合に連携します。

例

例 1：トラブルシューティングガイド

ユーザー：「Slack 連携に接続できないというメールがユーザーから何度も届きます。トラブルシューティングガイドを作成してください。」

良い出力例：

トラブルシューティング：Slack 連携に接続できない

症状

「Connect to Slack」をクリックすると、次のいずれかのエラーが表示されます。

• Authorization failed. Please try again.
• 確認メッセージが表示されないまま、ページが設定画面に戻ります。
• Slack が開き、「このアプリはワークスペースの管理者によって承認されていません。」と表示されます。

すぐに試せる解決策

1. **別のブラウザーを試します。**ブラウザーの拡張機能（特に広告ブロッカー）が OAuth リダイレクトを妨げることがあります。シークレット／プライベートウィンドウを開いて、もう一度試します。
2. **Slack の権限を確認します。**Slack のワークスペース管理者またはオーナーである必要があります。Slack 管理者に権限を付与してもらうか、管理者に連携を完了してもらいます。

解決しない場合

原因：Slack ワークスペースの制限

Slack ワークスペースで、新しいアプリに管理者の承認が必要な場合があります。

• 診断：「このアプリはワークスペースの管理者によって承認されていません。」と表示される場合は、これが原因です。
• **解決策：**Slack 管理者に、Slack Admin > Apps > Manage > 「[Product Name]」を検索 > Approve の順に操作して、アプリを承認してもらいます。

例 2：API ドキュメント

ユーザー：「Webhook エンドポイントのドキュメントを作成してください。イベントデータを含む POST リクエストを受け付け、成功時に 200 を返します。」

**良い出力の方針：**API テンプレートに正確に従います。認証の詳細、すべてのパラメーターとその型、必須／任意の区別、実際に動作する curl の例、説明付きのすべてのレスポンスコード、レート制限、再試行ポリシーを記載します。開発者はこのドキュメントからコピーして貼り付けるため、コードスニペットはすべて実際に動作する必要があります。