write-better-error-messages

より良いエラーメッセージを書く

このスキルを使って、具体的で落ち着きがあり、責任を明確にし、役に立つエラーメッセージを作成します。

出典

このスキルは、Wix UX が公開した Jenni Nadler の UX 記事「困ったときこそ、より良いエラーメッセージを書く」を参考にしています。記事の指針と、注釈付きのスクリーンショット（悪いメッセージのモーダル、改善したメッセージのモーダル、汎用的な表現とわかりにくい表現の比較、エラー一覧ボード）に示された教訓を取り入れています。

基本の確認事項

エラーメッセージを書く前、または承認する前に、次の質問に答えてください。

1. 何が起きましたか？
2. なぜ起きましたか？製品が正確に伝えられる、最も役立つ詳細レベルで説明してください。
3. 影響を受けなかったことはありますか？ユーザーに安心してもらう必要があれば説明してください。
4. ユーザーは今、何ができますか？
5. それでも解決しない場合、ユーザーは何ができますか？

製品がこれらの質問に答えられない場合は、コピーだけの問題ではなく、製品またはエンジニアリング上の課題として扱ってください。

避けること

• 重大な状況では、ふざけた口調やくだけすぎた口調を使わないでください。金銭、公開、作業の継続、アカウントへのアクセス、データ、ユーザーの信頼に関わるフローでは、「あっ」「おっと」「しまった」などの表現や冗談を避けてください。
• ユーザーを責めないでください。問題と復旧方法に焦点を当ててください。
• ユーザーが自社製品を操作している場面で、第三者を責めないでください。「[サービス] から応答がありません」よりも、「[サービス] への接続に問題が発生しています」を優先してください。
• ユーザーの行動に役立たない限り、実装の詳細を見せないでください。「取得」「認証情報が拒否されました」「500」「不明な例外」などの用語は、結果と次の手順に置き換えてください。
• システムがより詳しい情報を把握しているのに、「問題が発生しました」で済ませないでください。具体的な診断ができない場合に限り、汎用的なメッセージを使えます。その場合も、次の手順や別の解決方法を含めてください。
• 「具体的」と「わかりやすい」を混同しないでください。権限、トークン、スコープ、設定に言及していても、ユーザーが何をすればよいかわからなければ、わかりにくいメッセージです。

推奨すること

• 結果を最初に伝えてください。「アカウントに接続できませんでした」「画像をアップロードできませんでした」「変更は保存されましたが、メールは送信されませんでした」などです。
• 可能であれば理由を説明してください。「ファイルが 25 MB を超えているため」「セッションの有効期限が切れたため」「こちら側で問題が発生しているため」などです。
• 保持されている作業について、ユーザーに安心してもらいましょう。「下書きは保存されています」「請求設定は変更されていません」「まだ誰も招待されていません」などです。
• 具体的な次の手順を伝えてください。「もう一度接続してください」「25 MB 未満のファイルを選んでください」「もう一度サインインしてください」「ポップアップが許可されていることを確認してください」などです。
• ユーザーが行き詰まる可能性がある場合は、別の方法を用意してください。サポートへのリンク、ヘルプ記事、再試行、キャンセル、下書きの保存、データのダウンロード、カスタマーケアへの問い合わせなどです。
• 深刻な状況や回復不能な状況で共感を示す場合に限り、「どうぞ」を控えめに使ってください。単なる埋め草として使わないでください。

書き換えの手順

1. 状況と重要度を特定します。ユーザーの目的、表示箇所、リスクにさらされているデータ、ユーザーが自力で復旧できるか、エラーによってフローが止まるかを確認してください。
2. 必要に応じてエンジニアリングまたはプロダクトチームと原因を整理します。発生条件、頻度、判明している原因、影響を受ける状態、現実的な解決策を確認してください。
3. 現在のメッセージを分類します。
   • 汎用的：利用可能な情報を隠している表現。「問題が発生したため、この操作を完了できませんでした」などです。
   • わかりにくい：説明を試みていますが、ユーザーが何をすればよいかわかりません。「要求された権限を許可してから、もう一度お試しください」などです。
   • 専門用語が多い：ユーザーに見える結果ではなく、内部の仕組みを示しています。
   • 責任転嫁：体験に責任を持たず、ユーザーや連携先のせいにしています。
   • 口調が不適切：重要度に対して、ふざけすぎている、大げさすぎる、またはくだけすぎています。
4. 次の構成で下書きを作成します。
   • タイトル：ユーザーに見える結果。
   • 本文：簡潔な原因と、必要に応じた安心材料。
   • アクション：最優先の復旧手順。
   • 別の方法：再試行で解決しない可能性がある場合のサポートまたはヘルプへの案内。
5. ユーザーの理解、復旧、製品への信頼に役立たない文は削除します。
6. 最終的な文面が「基本の確認事項」を満たしているか確認します。

スクリーンショットから導き出したパターン

UI コピーを確認する際は、記事のスクリーンショットにある次のパターンを参考にしてください。

• 悪い例のモーダル：第三者に責任を押しつける表現、データ取得に関する技術的な言い回し、「後でもう一度お試しください」とともに、「おっと！問題が発生しました」と表示します。トーンの不一致、責任転嫁、専門用語、具体性に欠ける次のステップとして診断してください。
• 良い例のモーダル：「アカウントに接続できませんでした」に加え、「変更は保存されました」、プロダクト側に原因があることを率直に伝える説明、「もう一度接続をお試しください」、そしてカスタマーケアへの代替手段を示します。結果、安心材料、原因、次のステップ、代替手段という構成を目標にしてください。
• 一般的すぎる例と不明瞭な例の比較：「問題が発生しました……」は、ほとんど何も伝えていないため一般的すぎます。「要求された権限を許可してください……」は、どこでどのように操作すればよいかを伝えず、わかりにくい表現を使っているため不明瞭です。具体的な状況と、実行可能な復旧手順を示して、どちらも改善してください。
• インベントリのスクリーンショット：ボードやスプレッドシートには、メッセージ、表示条件、担当者、優先度、エラーの種類、発生頻度、ブロックされるフロー、期限、ステータス、最終的なコピーを記録します。エラーの改善は、UX ライティングだけでなく、部門横断で取り組む作業です。

インベントリとレビュー

複数のエラーをまとめて扱う場合は、簡単なインベントリを作成するか、既存のものを更新してください。

項目	目的
現在のメッセージ	ユーザーに表示されている文言そのものです。
表示条件	どのような条件で表示されるかを示します。
原因が判明しているか	エンジニアリングチームが原因を特定できるかどうかを示します。
発生頻度	ユーザーがどの程度の頻度で遭遇するかを示します。
ブロックするか	タスクの完了を妨げるかどうかを示します。
影響を受けた状態	何が変更され、失敗し、または維持されたかを示します。
担当者	プロダクト、エンジニアリング、デザイン、ライティングの担当者です。
提案するコピー	修正後のタイトル、本文、アクションです。
フォローアップ	計測、デザインの変更、サポートリンク、バックエンドの修正などです。

頻繁に発生するエラーや、重要なフローの完了を妨げるエラーを優先してください。実際の利用データが得られたら、リリース済みのエラーを見直してください。特に、幅広く使えるフォールバックメッセージを用いてリリースした新しいプロダクトでは、必ず見直しましょう。

出力形式

ユーザー向けに書き直す場合は、次の形式を優先してください。

Current: "..."
Issue: Generic / unclear / jargon / blame / tone mismatch / missing next step
Rewrite:
Title: ...
Body: ...
Primary action: ...
Fallback: ...
Reasoning: ...

理由は簡潔にし、ユーザーにとって何が変わったかに基づいて説明してください。