Chaos and Order

💡 왼쪽 원문을 읽으면서 오른쪽에 따라 써보세요. Tab 키로 힌트를 받을 수 있습니다.

원문 렌더가 준비되기 전까지 텍스트 가이드로 표시합니다.

はじめに

顧客と仕事をしていると、良いコードを書くことと同じくらい、時にはそれ以上に重要なことがあります。それはドキュメントによるコミュニケーションです。一枚の提案書、一行のリリースノート、一通の障害報告メールが、顧客の信頼を築くこともあれば、崩すこともあります。

どれほど技術的に優れた仕事をしても、それを顧客が理解できる言葉で伝えられなければ、その価値は半分に減ってしまいます。逆に、平凡な仕事であっても、明確で信頼感のあるドキュメントで届ければ、顧客は「このチームは仕事をきちんとやる」という印象を持ちます。

本稿では、顧客に届ける代表的なドキュメントの種類を見たうえで、読者に配慮した書き方、明確さと構成とトーン、悪い例と良い例、そして文書中の表現が契約上の約束になり得るという点まで、実務的な視点で整理します。

一つ先にお伝えします。本稿の法的含意を扱う部分は一般的な注意事項であり、法律的な助言ではありません。実際の契約文言や保証表現については、必ず所属組織の法務チームや契約担当者にご相談ください。

なぜ顧客ドキュメントが信頼を生むのか

顧客は、私たちが毎日何をしているかをリアルタイムで見ているわけではありません。彼らが私たちのチームを判断する根拠は、ほとんどが私たちの届けたドキュメントと会話です。つまり、ドキュメントは私たちのチームの代理人です。

信頼は、次のような瞬間に積み上がり、あるいは崩れます。

- 提案書を読んで「このチームは私たちの課題を正確に理解している」と感じたとき

- 障害が発生したとき、隠したりごまかしたりせず、何が起きたかを正確に説明したとき

- リリースノートを見て「今回何が変わったのか明確だ」と安心したとき

- 議事録を見て「自分の発言が正確に記録されている」と確認したとき

逆に、曖昧なドキュメント、誇張された約束、辻褄の合わない説明は信頼をむしばみます。顧客はドキュメントの隙間から、チームの隙間を読み取ります。

良い顧客ドキュメントがもたらす実質的な利点をまとめると、次のとおりです。

| 利点 | 説明 |

| --- | --- |

| 誤解の減少 | 明確なドキュメントは再確認メールと繰り返しの会議を減らします |

| 信頼の形成 | 一貫して正直なドキュメントは長期的関係の土台になります |

| リスク管理 | 合意内容が文書に残れば、紛争時の根拠になります |

| チームの拡張性 | 担当者が変わっても、ドキュメントが文脈をつなぎます |

| 意思決定の速さ | よく整理されたドキュメントは顧客の承認速度を高めます |

ドキュメント種類ごとのガイド

顧客向けドキュメントは、目的と読者、盛り込むべき内容がそれぞれ異なります。まず全体像を表で整理します。

| --- | --- | --- | --- |

それでは、各ドキュメントを一つずつ見ていきます。

提案書 (Proposal)

提案書の目的は自慢ではなく、理解と説得です。良い提案書は、自社の技術を並べる前に、顧客の課題を先に正確に突きます。

提案書に盛り込むべき要素は次のとおりです。

- 課題と背景: 顧客が置かれた状況を理解していることを示します

- 目標と成功基準: 何が成功かを測定可能に定義します

- アプローチ: どのように課題を解くかを大きな絵で説明します

- スケジュールとマイルストーン: いつ何を届けるかを明示します

- 費用と前提: 費用構造とその根拠となる前提を示します

- チームと実績: なぜ自社が適任かの根拠を提示します

注意すべき点は、提案書に書いた成果予測や効果の数値が、後に期待値の根拠になり得ることです。「性能が大幅に改善します」のような表現より、「同一条件のベンチマークで応答時間の短縮を目標とします」のように、条件と目標を明確にするほうが安全です。

SOW (作業範囲記述書, Statement of Work)

SOWは、顧客ドキュメントの中でも法的な重みが最も大きい部類に入ります。何をして、何をせず、それぞれの責任が何かを定義するからです。

SOWで特に気を配るべき部分は次のとおりです。

| セクション | なぜ重要か |

| --- | --- |

| 範囲(Scope) | 作業の境界を定めます。曖昧だと範囲拡大の紛争につながります |

| 成果物(Deliverables) | 何をいつ届けるかを具体的に明示します |

| 前提(Assumptions) | どの前提の上でスケジュールと費用を見積もったかを示します |

| 除外項目(Out of Scope) | やらないことを明示し、誤解を防ぎます |

| 受入基準(Acceptance) | 何を満たせば完了と認められるかを定義します |

特に「除外項目」を明示的に書くことが重要です。顧客はしばしば、SOWにない作業も当然含まれると期待するからです。何を含むかと同じくらい、何を含まないかを書いておくと、後続の紛争を大きく減らせます。

APIドキュメント

APIドキュメントの読者は開発者です。開発者はマーケティングの文句を求めていません。正確なリクエスト形式、レスポンス形式、認証方法、エラーコード、そしてコピーしてすぐ動かせる例を求めています。

良いAPIドキュメントの構成要素は次のとおりです。

- はじめに: 認証キーの発行から最初の呼び出しまでを5分で

- 認証: トークンをどう発行し、ヘッダーにどう載せるか

- エンドポイントリファレンス: 各エンドポイントのパラメータとレスポンス

- コード例: 実際に動作するリクエストとレスポンスの組

- エラーコード: 各エラーの意味と対処方法

- 変更履歴: バージョン間で何が変わったか

例を書くときは、実際に動作するかを必ず確認しなければなりません。ドキュメントの例が動作しないと、開発者はただちにドキュメント全体を不信に思います。以下は、認証ヘッダーを載せてユーザー一覧を取得するリクエスト例です。

GET /v1/users?limit=20

Host: api.example.com

Authorization: Bearer YOUR_API_TOKEN

Accept: application/json

レスポンス (200 OK):

{

"data": [

{ "id": "usr_001", "name": "Kim", "role": "admin" }

"has_more": false

}

リリースノート

リリースノートは、顧客に「今回何が変わったか」を透明に知らせる文書です。内部のコミットメッセージをそのまま貼り付けるのではなく、利用者の視点で何が変わったかを説明する必要があります。

効果的なリリースノートの構成は次のとおりです。

- 新規(New): 新たに追加された機能

- 改善(Improved): 既存機能の向上

- 修正(Fixed): バグ修正

- 注意(Breaking): 後方互換を壊す変更、移行の案内

特に後方互換を壊す変更は目立つように強調し、利用者が何をすべきかを具体的に案内する必要があります。

障害報告 (Incident Report)

障害報告は、信頼が最も大きく試される瞬間の文書です。このとき、正直さと明確さが何より重要です。隠したり責任を回避したりする印象を与えると、技術的対応がどれほど優れていても信頼を失います。

良い障害報告には次が含まれます。

| セクション | 内容 |

| --- | --- |

| 概要 | 何が起きたかを一〜二文で |

| 影響範囲 | 誰が、どれくらいの間、どんな影響を受けたか |

| タイムライン | 検知、対応、復旧の時刻ごとの流れ |

| 根本原因 | なぜ発生したか |

| 対応事項 | 直ちにどう対応したか |

| 再発防止 | 今後何を変えるか |

非難ではなく、事実と改善に焦点を当てること(ブレームレス)が、良い障害報告の核心です。

議事録 (Meeting Minutes)

議事録の価値は、「決まったこと」と「やるべきこと」を明確に残す点にあります。会話をそのまま書き取る速記録ではなく、決定事項と実行項目を中心に整理する必要があります。

- 出席者と日時

- 議論の議題

- 決定事項: 何を合意したか

- アクションアイテム: 誰が、何を、いつまでに

- 未決事項: 次に扱う内容

アクションアイテムには、必ず担当者と期限を明示してください。担当者のいないアクションアイテムは、誰もやりません。

読者への配慮、明確さ、構成、トーン

ドキュメントの品質は、結局、読者がどれだけ容易に理解し信頼するかで決まります。

読者への配慮 (Audience Awareness)

同じ内容でも、読者によって書き方を変える必要があります。技術読者と非技術読者を区別することが出発点です。

| 読者タイプ | 求めるもの | 避けるべきこと |

| --- | --- | --- |

| 非技術の意思決定者 | ビジネスへの影響、費用、スケジュール、リスク | 内部実装の詳細、専門用語の乱用 |

| 技術実務者 | 正確な仕様、例、制約事項 | 抽象的なマーケティング文句、曖昧な説明 |

| 混在読者 | 要約は易しく、詳細は付録に | 最初から最後まで一つの難易度 |

混在読者に向けた良い戦略は、「要約は誰でも理解できるように、技術的詳細は付録や別セクションに」配置することです。

明確さ (Clarity)

- 一つの文には一つの考えだけを盛り込みます

- 能動態を基本にします。「処理が行われました」より「システムが要求を処理しました」

- 略語は初出時に展開します

- 曖昧な修飾語を避けます。「まもなく」「大幅に」「十分に」は測定可能な表現に置き換えます

構成 (Structure)

- 最も重要な結論を前に置きます(逆ピラミッド)

- 見出しと小見出しで拾い読みできるようにします

- リストと表で情報を視覚的に分解します

- 長い文書には目次と要約を付けます

トーン (Tone)

トーンは信頼のかなりの部分を左右します。以下は守るべきことと避けるべきことを整理した表です。

| 状況 | 推奨 (Do) | 回避 (Don't) |

| --- | --- | --- |

| ミスの認め方 | 事実を明確に示し改善策を提示 | 言い訳や責任回避 |

| 遅延の通知 | 新しいスケジュールと理由を具体的に | 曖昧に先送り |

| 技術説明 | 読者の水準に合わせて易しく | 専門用語で圧倒 |

| 悪い知らせの伝達 | 正直に、代替案とともに | 隠したり縮小したり |

| 依頼事項の伝達 | 丁寧かつ具体的に | 命令調や曖昧に |

悪い例 vs 良い例 (Before / After)

抽象的な原則より、具体的な例のほうがはるかに伝わります。いくつか代表的なビフォー/アフターを見ます。

障害報告

まず、曖昧な障害報告です。

[Before] 障害のお知らせ

こんにちは。本日サービスに一時的な問題がありましたが、

現在は正常化しました。ご不便をおかけして申し訳ございません。

今後さらに努力してまいります。

この報告は、何がいつ起きたか、誰が影響を受けたか、何が原因だったか、再発防止のために何をするかを何も伝えていません。以下は改善版です。

[After] 決済API遅延障害報告 (2026-06-28)

概要:

2026-06-28 14:02から14:37まで約35分間、決済APIの

応答遅延が発生しました。この間、一部の決済リクエストが

タイムアウトで失敗しました。

影響範囲:

- 対象: クレジットカード決済を試みた利用者の約12パーセント

- 期間: 14:02 - 14:37 (35分)

- 症状: 決済ボタンの応答遅延、一部リクエストの失敗

タイムライン:

- 14:02 決済API応答時間の急増を検知(監視アラート)

- 14:09 担当チームが対応開始

- 14:25 データベース接続プールの飽和が原因と確認

- 14:37 接続プール拡張後に正常化を確認

根本原因:

決済トラフィックの急増でデータベース接続プールが

飽和し、待機していたリクエストがタイムアウトで

失敗しました。

対応事項:

- 直ちに接続プールのサイズを拡大し処理量を回復

- 失敗した決済は二重請求なく自動で再処理を完了

再発防止:

- 接続プール使用率のアラート閾値を引き下げ

- トラフィック急増に備えた自動拡張ポリシーを検討(7月中)

二つの版の違いは明確です。改善版は、事実、影響、原因、対応、再発防止をすべて盛り込み、顧客が状況を正確に理解して安心できるようにしています。

リリースノート

内部コミットをそのまま貼った悪い例です。

[Before] v2.4.0 リリース

- fix bug

- update deps

- refactor auth module

- WIP dashboard

- misc changes

利用者は、このノートから自分にとって何が変わったのかまったく分かりません。以下は利用者視点で書き直した版です。

[After] v2.4.0 リリースノート (2026-06-25)

新規:

- ダッシュボードから期間別の使用量をCSVで書き出せます。

改善:

- ログイン後のダッシュボード初回読み込み速度を改善しました。

- メール通知の送信時刻表記を利用者のタイムゾーンに統一しました。

修正:

- パスワード再設定リンクが有効期限を誤って表示していた

問題を修正しました。

注意(後方互換の変更):

- 旧バージョンの認証トークン形式は2026-08-01から

サポートを終了します。移行案内: 設定 - セキュリティで

トークンを再発行してください。

議事録

曖昧な議事録です。

[Before] 6月30日会議

いろいろな話をして、おおむね良い方向で合意しました。

次回さらに議論することにしました。

何を合意したか、誰が何をするか分かりません。以下は決定とアクション中心に整理した版です。

[After] プロジェクトキックオフ議事録 (2026-06-30)

日時: 2026-06-30 10:00 - 11:00

出席: 顧客側李代表、朴チーム長 /

自チーム金PM、崔開発

決定事項:

- 一次リリース目標日を2026-08-15に確定

- 認証方式はOAuthベースで進行

- 週次進捗会議は毎週木曜午前10時

アクションアイテム:

- API仕様の初稿作成: 崔開発 / 2026-07-07まで

- アクセス権限とテストアカウントの提供: 朴チーム長 / 2026-07-04まで

- SOW最終版の回覧: 金PM / 2026-07-08まで

未決事項:

- データ移行の範囲は次回会議で確定

約束と責任 — 法的含意への注意

改めて強調します。本セクションは一般的な注意事項であり、法律的な助言ではありません。実際の契約文言や保証表現については、必ず法務チームまたは契約担当者にご相談ください。

文書中の表現は、しばしば私たちが意図した以上に強い約束として解釈され得ます。特に提案書、SOW、メールに書いた表現が、契約上の期待の根拠になる場合があります。

危険な表現 vs 安全な表現

性能や可用性を扱うときは特に注意が必要です。以下の表は、よく使う危険な表現と、より安全な代替です。

| 危険な表現 | なぜ危険か | より安全な表現 |

| --- | --- | --- |

| 100パーセントの無停止を保証します | 現実的に守れない絶対的な約束 | 目標可用性99.9パーセントを基準に運用します |

| すべてのバグを直ちに解決します | 範囲と時間が無限に開く | 重大度基準に応じた対応時間を定義します |

| 完全に安全です | 絶対的なセキュリティは存在しない | 業界標準のセキュリティ慣行を適用します |

| いつでも無料で支援します | 無制限の義務を生み得る | 契約範囲内で支援を提供します |

| 必ず性能が向上します | 結果を無条件に保証 | 同一条件での向上を目標とします |

SLA表現で特に注意すべき点

SLA(サービスレベル合意)に関する表現は、実際に運用可能な水準だけを約束すべきです。

- 「保証する(guarantee)」という語は慎重に使います。守れることだけを保証します

- 可用性の数値は測定方法とともに定義します(何を、どの期間を基準に)

- 例外条件(定期メンテナンス、不可抗力など)を明示します

- 未達時にどうなるか(クレジット、対応手順)も併せて定義します

核心となる原則は単純です。守れないことを約束しないこと、そして約束したことは必ず測定可能に定義することです。

バージョン、承認、追跡

顧客ドキュメントは生きた文書です。時間とともに修正され、合意され、更新されます。だからこそ、バージョン管理と承認、変更追跡が必要です。

なぜ必要か

- どのバージョンを基準に合意したかを明確にするため

- 誰がいつ何を承認したかを残すため

- 変更履歴を通じて誤解と紛争を防ぐため

文書バージョン履歴の例

重要な文書には、冒頭または末尾に簡単なバージョン履歴の表を置くとよいでしょう。

| --- | --- | --- | --- | --- |

| 0.1 | 2026-06-20 | 金PM | 初稿作成 | レビュー中 |

| 0.2 | 2026-06-25 | 金PM | 範囲とスケジュールを修正 | レビュー中 |

| 1.0 | 2026-06-30 | 金PM | 顧客承認を反映した最終版 | 李代表承認 |

承認と追跡の実務的なコツ

- 文書のファイル名にバージョンを入れるか、文書管理システムのバージョン機能を活用します

- 承認はメールや文書システムの記録として残します。口頭承認だけでは、後で根拠が残りません

- 変更するときは、何がなぜ変わったかの要約を併せて残します

- 最終版は明確に「最終承認版」と表示し、どのバージョンが有効かの混同をなくします

ドキュメント文化

良い顧客ドキュメントは、個人の努力だけでは持続しません。チームの文化として根づく必要があります。

ドキュメント文化が健全なチームの特徴は次のとおりです。

- ドキュメント作成を付随的な雑務ではなく、業務の一部として認めます

- 共通テンプレートとスタイルガイドを備え、品質を一定に保ちます

- 文書もコードのようにレビューします。顧客に出す前に同僚がもう一度読みます

- 良い文書を書いた人を認め、共有します

- 古い文書を放置せず、定期的に更新します

ドキュメント文化を育てる具体的な方法をまとめると、次のとおりです。

| 実践 | 効果 |

| --- | --- |

| 文書テンプレートの標準化 | 品質のばらつきを減らし作成時間を短縮 |

| 顧客送付前の同僚レビュー | エラーとトーンの問題を事前に発見 |

| スタイルガイドの共有 | 用語と表現の一貫性を確保 |

| 文書例のライブラリ | 良い文書を再利用可能な資産に |

| 定期的な文書整理 | 古く誤った情報による混乱を防止 |

ドキュメントを上手に書くチームは、一朝一夕にはできません。小さな習慣が積み重なって文化になります。

チェックリスト

顧客に文書を送る前に、以下の項目を点検してください。

- [ ] この文書の主な読者が誰かは明確か

- [ ] 最も重要な結論や要約が前にあるか

- [ ] 技術水準が読者に合っているか(非技術読者に専門用語を乱用していないか)

- [ ] 曖昧な表現(まもなく、大幅に)を測定可能な表現に置き換えたか

- [ ] 守れない約束や誇張された保証表現はないか

- [ ] SLAや性能に関する表現が実際に運用可能な水準か

- [ ] アクションアイテムに担当者と期限があるか

- [ ] 誤字脱字と文法を確認したか

- [ ] 例やリンクが実際に動作するか

- [ ] バージョンと日付、作成者が表示されているか

- [ ] 送付前に同僚がもう一度読んだか

- [ ] 正直で敬意あるトーンを保っているか

このチェックリストをチームの共通習慣にすれば、ドキュメント品質の下限が目に見えて上がります。

おわりに

顧客ドキュメントは単なる形式ではなく、信頼を盛る器です。私たちがどれほど誠実に働くか、どれほど正直か、どれほど顧客に配慮するかが、文書の一文一文からにじみ出ます。

明確に書き、読者に配慮し、守れることだけを約束し、正直にコミュニケーションすること。これらの単純な原則が積み重なって、顧客の信頼になります。そして、その信頼はどんな技術的成果よりも長く残ります。

今日送る一通の文書が、私たちのチームへの印象を決めます。その一通を丁寧に書くことから、良いコミュニケーションが始まります。

参考資料

- [Google Technical Writing Courses](https://developers.google.com/tech-writing)

- [Google Developer Documentation Style Guide](https://developers.google.com/style)

- [Write the Docs](https://www.writethedocs.org/)

- [Microsoft Writing Style Guide](https://learn.microsoft.com/style-guide/welcome/)

- [Plain Language Guidelines](https://www.plainlanguage.gov/)

- [Stripe API Documentation](https://stripe.com/docs)

- [OpenAPI Specification](https://swagger.io/specification/)

- [Keep a Changelog](https://keepachangelog.com/)

- [Atlassian Incident Management Handbook](https://www.atlassian.com/incident-management)