技術文書を非技術者向けに書き直す
制約と失敗時の挙動は残し、実装の詳細を読者が対応づけられる結果に置き換える
あなたは技術コミュニケーションの編集者です。次の技術文書を、非技術者の読者向けに書き直してください。読者は［役割：プロダクトマネージャー、顧客、経営層など］です。条件：1）冒頭に、その読者にとって何を意味するかを一文で示す。2）技術的な概念が初めて出る箇所では、日常の経験に置き換えて説明し、新しい用語は持ち込まない。3）制約条件、失敗時の挙動、数値は残す。分かりやすくするためにリスクを削らない。4）原文で曖昧な点や欠けている情報は別に列挙し、「要確認」と記す。仕組みを比喩で置き換えないでください。 ［技術文書を貼り付けてください］
使い方
書き直したら、制約条件と失敗時の挙動を一行ずつ原文と突き合わせます。平易化で最も失われやすいのがこの二つです。
向いている場面
- エンジニアから API のレート制限の説明が来ました。営業が顧客との打ち合わせで、パラメータを読み上げるのではなく「なぜ失敗するのか、いつ失敗するのか」を説明できる必要があります。
- セキュリティ通知を経営層に送ります。経営層はそれを見てリリースを遅らせるか決めるため、制約条件と最悪のケースは残さなければなりません。
向いていない場面
- 読者が実際に手順を実行する場合です。その場合は手順書を書くべきで、用語を外すと実行できなくなります。
- 原文がまだレビュー中で、主要なパラメータが確定していない場合です。確定を待たないと、不確実さをより自信ありげな文章に翻訳するだけになります。
例
入力
この API は既定で毎秒20リクエストまで。超えると429を返すため、クライアント側で指数バックオフを実装しないと継続的な制限を受けることがある。
得られるもの
冒頭は「ピーク時に毎秒20回を超えると一部の操作は失敗するが、データは失われない」となります。429 とバックオフは「列に並ばされて追い返され、間を空けて再挑戦する」と説明し、20回・継続制限という境界は残します。「クライアント側の再試行は実装済みか」は要確認として別に挙げます。
よくある誤用
- 「専門用語はできるだけ避けて、とにかく分かりやすく」と頼むことです。境界が緩むと「継続的な制限」という最も残すべきリスクまで説明から抜け落ちます。
- 仕組みを比喩で置き換えることを許すことです。制限を「高速道路の渋滞のようなもの」と言うと、待てば自動で回復すると読めますが、実際はクライアント側の処理を変える必要があります。
こう変えると効く
- 読者を「経営層」から「カスタマーサポート」に変えます。同じ文書が「顧客に何が見え、どう答えるか」に書き換わり、現場向けになります。
- 「各説明のあとに、当てはまらない状況を一文で添える」を足します。平易化が過度な単純化になるのを防げます。