「READMEを英語で書いたら、チームメンバーから “What does this mean?” と言われた。」
技術的に正しくても、伝わらない英語文書は存在しないのと同じだ。グローバルチームでの技術文書には「英語が書ける」こととは別のスキルが必要になる。
この記事では、エンジニアが実務で書く技術文書（README・API仕様書・手順書・変更ログ）に使えるフレーズ30選を場面別に整理した。フレーズをそのまま使うだけで、英語技術文書のクオリティが変わる。
結論から言う。英語テクニカルライティングは「正しい英語を書く」のではなく「型に当てはめる」スキルだ。型を持てば、ネイティブでなくても読まれる技術文書を書ける。
英語テクニカルライティングと一般英語の違い
テクニカルライティングは「特定の読者に技術的な内容を正確・明確・簡潔に伝える」文書作成のことだ。一般英語とは3点が異なる。
- 対象読者が明確：特定の役割・スキルレベルの読者を想定する
- 行動促進が目的：読んで次に何をすべきかが明確になる
- 再現性が最優先：誰が読んでも同じ結果が出る指示の精度が求められる
この3点を意識するだけで、英語技術文書は大幅に改善する。
ドキュメント冒頭・概要を書くフレーズ（①〜⑥）
文書を開いた読者が「これは何のドキュメントか」「自分に関係あるか」を5秒で判断できる冒頭を設計する。
目的・対象読者を宣言するフレーズ
① “This document describes [何を説明するか]. It is intended for [対象読者].”
（このドキュメントは[何を説明するか]について述べています。[対象読者]向けです。）
最初の一文で「何の文書か」と「誰向けか」を宣言する。読者は自分に関係あるかを即座に判断できる。
② “This guide walks you through [プロセス]. By the end, you will be able to [達成できること].”
（このガイドでは[プロセス]を順を追って説明します。最後には[達成できること]ができるようになります。）
「By the end, you will be able to」はチュートリアル系文書の定番冒頭だ。読者のゴールを先に示す。
③ “This document assumes that you have [前提知識・環境]. If you are new to [X], see [関連ドキュメント] first.”
（このドキュメントは[前提知識・環境]があることを前提としています。[X]が初めての場合は、まず[関連ドキュメント]を参照してください。）
前提条件を明示することで、「自分のレベルには合わない」という離脱を防げる。
スコープ・メタ情報を定義するフレーズ
④ “This document covers [スコープ]. It does not cover [スコープ外].”
（このドキュメントは[スコープ]を扱います。[スコープ外]は対象外です。）
「何を扱わないか」を明示することで、読者の誤解を防げる。
⑤ “Prerequisites: [前提条件リスト]. Ensure these are installed and configured before proceeding.”
（前提条件：[前提条件リスト]。続ける前にこれらがインストールおよび設定済みであることを確認してください。）
手順書・セットアップガイドの冒頭に必ず設ける。事前確認を箇条書きで続ける。
⑥ “Version: [バージョン] | Last Updated: [更新日] | Maintainer: [担当者名またはチーム]”
（バージョン：[バージョン] | 最終更新日：[更新日] | メンテナー：[担当者名またはチーム]）
ドキュメントのメタ情報を冒頭に記載することで、情報の鮮度と責任の所在が明確になる。
手順・操作指示を書くフレーズ（⑦〜⑫）
手順書の英語は「曖昧さゼロ」が命だ。誰が読んでも同じ手順で同じ結果が出るように書く。
ステップバイステップの指示フレーズ
⑦ “Step 1: [アクション]. Step 2: [アクション].”
（ステップ1：[アクション]。ステップ2：[アクション]。）
ステップ番号を振ることで、読者が「どこまで終わったか」を追跡できる。
⑧ “Run the following command to [目的]:”
（[目的]を実行するには、以下のコマンドを実行してください：）
コマンドブロックの前にこの一文を置くことで、コマンドの「目的」が明確になる。コピペするだけのエンジニアも目的を理解できる。
⑨ “To [目的], navigate to [場所] and click [ボタン名].”
（[目的]のためには、[場所]に移動して[ボタン名]をクリックしてください。）
GUIとCLIのどちらにも応用できる指示フレーズだ。「目的 → 操作」の順で書く。
前提確認・完了確認フレーズ
⑩ “Before you begin, verify that [確認事項].”
（始める前に、[確認事項]であることを確認してください。）
手順の途中で詰まらないよう事前確認を促す。特に破壊的な操作の前に必ず置く。
⑪ “When complete, you should see [期待する結果 / 出力].”
（完了すると、[期待する結果/出力]が表示されます。）
期待する結果を示すことで、読者が「本当に成功したか」を自分で判断できる。
⑫ “If you encounter [エラーや問題], refer to the Troubleshooting section.”
（[エラーや問題]が発生した場合は、トラブルシューティングセクションを参照してください。）
エラー時の逃げ道を示すことで、読者が途中で詰まって離脱するのを防げる。
GitHubのコメント・PRでの英語表現も実務でよく使う。詳しくはGitHubコメントで使える英語フレーズ30選も参考にしてほしい。
技術仕様・APIを説明するフレーズ（⑬〜⑱）
API仕様書・技術仕様書では、フレーズの型を決めることで記述の一貫性が生まれる。
APIエンドポイント・パラメータを説明するフレーズ
⑬ “The [エンドポイント] endpoint accepts a [HTTP method] request and returns [レスポンス内容].”
（[エンドポイント]エンドポイントは[HTTPメソッド]リクエストを受け付け、[レスポンス内容]を返します。）
APIエンドポイントの説明の基本形だ。メソッド・受け付けるもの・返すものをセットで説明する。
⑭ “The [パラメータ名] parameter is [required / optional]. It specifies [説明] and must be [型 / 値の制約].”
（[パラメータ名]パラメータは[必須/任意]です。[説明]を指定し、[型/値の制約]でなければなりません。）
パラメータ説明の必須要素：必須/任意・役割・型/制約の3点を1文で記述する。
⑮ “If [パラメータ] is not provided, it defaults to [デフォルト値].”
（[パラメータ]が指定されない場合、デフォルトは[デフォルト値]です。）
デフォルト値は必ず明記する。「未指定の場合どうなるか」が不明な仕様書は使いにくい。
戻り値・エラーレスポンスを説明するフレーズ
⑯ “On success, the API returns a [200 OK] response with the following fields: [フィールドリスト].”
（成功した場合、APIは以下のフィールドを含む[200 OK]レスポンスを返します：[フィールドリスト]。）
成功時のレスポンスは「ステータスコード＋返却フィールド」をセットで記述する。
⑰ ‘Error responses follow the format: { “error”: “[エラーコード]”, “message”: “[メッセージ]” }.’
（エラーレスポンスは次の形式に従います：{ “error”: “[エラーコード]”, “message”: “[メッセージ]” }。）
エラーフォーマットを統一して文書化することで、クライアント側の実装コストが下がる。
⑱ “Returns a [404 Not Found] if [条件], or a [400 Bad Request] if [条件].”
（[条件]の場合は[404 Not Found]、[条件]の場合は[400 Bad Request]を返します。）
エラーコードと「いつ発生するか」を紐づけて説明する。エラーコードの列挙だけでは不十分だ。
英語仕様書・設計書の全セクションの書き方は、英語仕様書・設計書の書き方も参考にしてほしい。
注意・警告・制約を書くフレーズ（⑲〜㉔）
Note・Warning・Cautionの3段階を使い分けることが、英語テクニカルライティングの基本だ。
Note / Warning / Cautionの使い分け
| 種別 | 重要度 | 使う場面 |
|---|---|---|
| Note | 低 | 知っておくと便利な補足情報 |
| Warning | 中〜高 | 無視するとシステムや業務に重大な影響 |
| Caution | 最高 | 操作が不可逆でデータ損失・障害の可能性あり |
⑲ “Note: [補足情報・知っておくと便利な情報].”
（注記：[補足情報・知っておくと便利な情報]。）
「Note」はデータ損失や障害に直結しない補足情報に使う。読者のプラスになる情報を添えるときに使う。
⑳ “Warning: [無視するとシステムや業務に重大な影響を与える情報].”
（警告：[無視するとシステムや業務に重大な影響を与える情報]。）
「Warning」はシステム障害・データ損失・セキュリティ侵害につながりうる情報に使う。見落とすと問題が起きるレベルだ。
㉑ “Caution: [誤った操作をすると取り返しのつかない結果を招く情報].”
（注意：[誤った操作をすると取り返しのつかない結果を招く情報]。）
「Caution」は最高度の警告だ。本番データの削除・不可逆な操作の前に必ず置く。
既知の制限・非推奨を伝えるフレーズ
㉒ “Known limitation: [制限の内容]. Workaround: [回避策].”
（既知の制限：[制限の内容]。回避策：[回避策]。）
既知の制限を「Known limitation」として文書化することで、ユーザーが「バグか仕様か」を迷わない。
㉓ “This feature is not supported in [バージョン / 環境]. It will be available in [将来のバージョン].”
（この機能は[バージョン/環境]ではサポートされていません。[将来のバージョン]で利用可能になります。）
「いつ使えるか」を示すことで、ユーザーの不満を軽減できる。
㉔ “Deprecated: [機能名] will be removed in [バージョン]. Use [代替手段] instead.”
（非推奨：[機能名]は[バージョン]で削除されます。代わりに[代替手段]を使用してください。）
非推奨の告知は「削除時期」と「代替手段」をセットで示す。移行コストを読者に与えることが責任ある文書だ。
レビュー・更新・バージョン管理フレーズ（㉕〜㉚）
技術文書は「書いて終わり」ではない。レビュー・更新・改版を継続することで信頼性が保たれる。
変更ログ・改版履歴を書くフレーズ
㉕ “| Version | Date | Author | Changes |”
（| バージョン | 日付 | 著者 | 変更内容 |）
変更履歴テーブルの標準ヘッダーだ。すべてのドキュメントにこのテーブルを設けると運用が楽になる。
㉖ “Added [追加した機能/セクション]. Updated [更新した内容]. Removed [削除した内容].”
（[追加した機能/セクション]を追加。[更新した内容]を更新。[削除した内容]を削除。）
変更ログの記述フォーマットだ。「Added / Updated / Removed」の動詞で変更の種類を明示する。
㉗ “This section is under construction. Last updated: [日付]. For questions, contact [担当者].”
（このセクションは作成中です。最終更新日：[日付]。質問は[担当者]まで。）
未完成のセクションを明示することで、不完全な情報に従って作業するリスクを防げる。
レビュー依頼・フィードバック対応フレーズ
㉘ “Please review this document and provide feedback by [日付]. Focus especially on [確認ポイント].”
（[日付]までにこのドキュメントをレビューしてフィードバックをください。特に[確認ポイント]に注目してください。）
レビュー依頼は「期限」と「フォーカスする箇所」をセットで伝えることでレビュアーの負担を減らせる。
㉙ “Addressed your feedback on [セクション名]. The section has been updated to [変更内容].”
（[セクション名]へのフィードバックに対応しました。[変更内容]にセクションを更新しました。）
フィードバック対応を文書化することで、レビュアーが次のレビューで変更点を素早く確認できる。
㉚ “If you find any inaccuracies or outdated information, please open an issue or submit a PR.”
（不正確または古い情報を見つけた場合は、IssueをオープンするかPRを送ってください。）
OSSドキュメントでよく見るフレーズだ。貢献を招き入れる表現として文書の末尾に置くことが多い。
PRでのフィードバック対応フレーズをさらに学びたい方は、英語プルリクエストの書き方も参考にしてほしい。
読まれる英語技術文書を書く3つの鉄則
鉄則①：能動態・現在形・短文を徹底する
英語テクニカルライティングには「文体の3ルール」がある。能動態・現在形・短文だ。
- 能動態：「Data is sent by the client」→「The client sends data.」
- 現在形：「You will click」→「Click the button.」
- 短文：1文20語以内を目標にする
受動態・過去形・長文は読者の理解スピードを下げる。端的な指示形が技術文書の正解だ。
鉄則②：「何をすべきか」を先頭に書く
技術文書の読者は「自分が何をすべきか」を探して読んでいる。
「Click Save to preserve your changes.」ではなく「To save your changes, click Save.」と書く。目的を先に、操作を後に書くことで、読者は最初の数語で自分がすべきことを把握できる。
鉄則③：用語を統一して混乱を排除する
「user」「account」「member」が混在すると、同じ概念を指すのか別の概念なのかが不明になる。同じ概念を複数の言葉で表現することは避ける。
用語の統一はグロッサリー（用語集）を冒頭に設けるか、最初に使った箇所に定義を入れるのが標準的な対処法だ。
技術文書を書くだけでなく、チームへのナレッジ共有を英語で進めるフレーズはエンジニアの英語ナレッジ共有術にまとめている。
英語AS-IS/TO-BE分析術｜課題ヒアリング・ギャップ分析・改善提案フレーズ30選まとめ：英語テクニカルライティングは「型」があれば誰でも書ける
英語テクニカルライティングで大切なのは英語力ではなく、構造・型・用語の統一だ。
今日から使えることをまとめる：
- ドキュメント冒頭に「目的・対象読者・前提条件・スコープ」を明示する
- 手順書は「Step番号 + 動詞から始まる命令文」で書く
- APIドキュメントは「エンドポイント・パラメータ・レスポンス・エラー」をセットで記述する
- Note / Warning / Caution を重要度に応じて使い分ける
- 変更ログには「Added / Updated / Removed」の動詞を使う
- 能動態・現在形・短文（1文20語以内）を徹底する
フレーズの型を手に入れた今、手元の技術文書を1つ開いて1つ改善してみよう。
コメント