「英語でドキュメントを書いたのに、海外の開発者からフィードバックがほとんど返ってこない」「READMEを英語にしたら、むしろ読みにくくなった気がする」——そんな経験はありませんか？実は、英語が書けることと、テクニカルライティングができることはまったく別のスキルです。このセクションでは、日本人エンジニアが陥りがちな落とし穴と、伝わるドキュメントの根本原則を整理します。
なぜ日本人エンジニアの英語ドキュメントは「伝わらない」のか
日本語直訳が生む3つの典型的な落とし穴
日本語には「主語を省く」「受け身を多用する」「長い修飾節を重ねる」という文章習慣があります。これをそのまま英語に持ち込むと、読み手が「誰が何をするのか」を理解するために余計な認知コストを払うことになります。
- 主語の省略：日本語では自然でも、英語では「誰がやるのか」が不明になる
- 受け身の多用：「〜されます」「〜が行われます」は英語でも受動態になり、責任の所在が曖昧になる
- 長文・多重修飾：1文に複数の条件を詰め込むと、英語ネイティブでも読み解くのに時間がかかる
テクニカルライティングと「普通の英語」は何が違うのか
ビジネスメールや会話で使う英語は、多少あいまいでも文脈で補えます。しかしAPI仕様書やREADMEは、読み手が「流し読み（スキャン）」しながら必要な情報だけを拾う使い方をします。テクニカルライティングが目指すのは、「正確さ」と「スキャナビリティ（流し読みのしやすさ）」の両立です。文学的な表現や丁寧な前置きは不要で、むしろ邪魔になります。
ドキュメント英語に求められる3大原則：簡潔性・能動態・一貫性
まず、NG例とOK例を並べて確認してみましょう。
| NG（日本語直訳調） | OK（テクニカルライティング調） |
|---|---|
| The configuration file should be edited by the user before the application is started. | Edit the configuration file before starting the application. |
| It is possible that an error may be returned if the parameter is not correctly specified. | Returns an error if the parameter is invalid. |
| The process of the data uploading is being performed. | Uploading data… |
- 簡潔性（Clarity）：1文1メッセージ。余分な修飾語・前置きを削ぎ落とす
- 能動態（Active Voice）：「誰が何をする」を明確にする。受動態は例外的な場面のみ使う
- 一貫性（Consistency）：同じ概念には同じ単語を使い続ける。表記ゆれはドキュメント全体の信頼性を下げる
この3原則は、この記事全体を通じて繰り返し登場するキーワードです。API仕様書・README・リリースノートのどれを書くときも、まずこの3つに立ち返る習慣をつけましょう。
テクニカルライティングの基礎文法：ドキュメント英語の「型」を身につける
英語ドキュメントを書く上で、文法的に正しいかどうかよりも重要なのが「型を守っているか」です。テクニカルライティングには業界共通のルールがあり、それを知るだけで読みやすさが格段に向上します。このセクションでは4つの基礎ルールを具体例とともに解説します。
能動態 vs 受動態：どちらをいつ使うべきか
テクニカルライティングの基本は能動態を優先することです。主語が明確になり、文が短くなり、読み手が誰が何をするのかを即座に理解できます。ただし、受動態が適切な場面も存在します。
| 場面 | NG（受動態） | OK（能動態 or 受動態） |
|---|---|---|
| 手順の指示 | The file should be saved by the user. | Save the file. |
| 機能の説明 | The data is processed by the system. | The system processes the data. |
| 主語が不明・不要 | — | The error was logged automatically.（受動態OK） |
| 結果を強調したい | — | The token is invalidated after 24 hours.（受動態OK） |
命令形で書く：手順・指示文の黄金ルール
手順説明では「動詞の原形で文を始める」命令形が世界標準です。日本人が書きがちな「Please enter your credentials」のような丁寧表現は、ドキュメントでは冗長に見えます。命令形は失礼ではなく、むしろプロフェッショナルな書き方です。
- Run / Execute — コマンドを実行する
- Install / Uninstall — インストール・削除する
- Configure / Set — 設定する
- Open / Close — 開く・閉じる
- Enter / Specify — 入力・指定する
- Verify / Confirm — 確認する
曖昧語・冗長表現を排除するリファクタリング術
ドキュメントの英語はコードと同じで、リファクタリングが必要です。意味が変わらないなら短い表現を選ぶのが鉄則です。以下の置き換えリストを参考にしてください。
- utilize → use
- in order to → to
- at this point in time → now
- due to the fact that → because
- a number of → several / many
- it is possible to → you can
- perform an installation of → install
一貫性を保つ：用語・表記ゆれを防ぐ語彙管理の考え方
同じ概念に複数の単語を使うと、読み手は「deleteとremoveは違う操作なのか？」と混乱します。1つの概念には1つの単語を徹底するのが、プロのテクニカルライターの鉄則です。
| NG（混在） | OK（統一） |
|---|---|
| delete / remove / erase を混在 | delete に統一 |
| user / account / member を混在 | user に統一 |
| click / press / select を混在 | 操作対象で使い分けを決めて統一 |
| error / exception / fault を混在 | コードベースに合わせて1語に統一 |
プロジェクトの初期段階でスプレッドシートや共有ドキュメントに「用語集」を作成し、使う単語と使わない単語を明記しておくと、チーム全体で表記ゆれを防げます。ドキュメントが増えるほどその効果は大きくなります。
README英語ライティング実践：読まれる・使われるREADMEの書き方
READMEはプロジェクトの「顔」です。どれだけ優れたコードを書いても、READMEが伝わらなければ誰にも使ってもらえません。読まれるREADMEには、決まった構成と各セクションの書き方のルールがあります。このセクションでは、標準構成から実際の英文フレーズまで、すぐに使える形で解説します。
READMEの標準セクション構成と各セクションの役割
OSSコミュニティで広く使われているREADMEの標準構成は次の6セクションです。それぞれ「何を・どの粒度で書くか」が異なります。
| セクション | 役割・書く内容 |
|---|---|
| Description | 何ができるツールか、誰のためのものかを1〜2文で伝える |
| Badges | ビルド状態・ライセンス・バージョンを視覚的に示す |
| Installation | 環境構築の手順をコマンド付きで番号順に示す |
| Usage | 基本的な使い方をコード例とともに示す |
| Contributing | 貢献方法・バグ報告・PRの送り方を案内する |
| License | ライセンス種別を明記する |
プロジェクト概要（Description）を1〜2文で書く技術
Descriptionで最も重要なのは、最初の1文に「何ができるか（What）」を凝縮することです。読者は概要を読んで「自分に必要かどうか」を3秒で判断します。
| 評価 | 例文 | 問題点 / 良い点 |
|---|---|---|
| NG | This is a tool that was made to help users who want to manage their tasks more efficiently in a simple way. | 主語が曖昧。「simple」「efficiently」など抽象語が多く、何をするツールか不明 |
| OK | TaskFlow is a command-line task manager that lets you create, prioritize, and track to-dos from your terminal. | ツール名・カテゴリ・具体的な機能を1文に凝縮。読者がすぐに用途を理解できる |
Description の公式テンプレート: “[ツール名] is a [カテゴリ] that [主要機能を動詞で列挙].” この型に当てはめるだけで、迷わず書けます。
インストール・使い方セクション：ステップ形式で迷わせない手順の書き方
Installationセクションで最も避けるべきは、説明文とコマンドを混在させることです。コマンドブロックと説明文を分離し、番号付きリストで書くことで、読者の認知負荷を大きく下げられます。
必要な環境・バージョンを箇条書きで示します。例: “Requires Node.js v18 or higher.”
説明文を1行書いてからコマンドを示します。例: “Clone the repository:” の後に git clone コマンドブロックを置きます。
“Install dependencies:” と書いてからコマンドブロックを続けます。説明とコマンドを1対1で対応させるのがポイントです。
“Verify the installation:” に続けて確認用コマンドと期待される出力例を示すと、読者が成功・失敗を判断できます。
コントリビューションガイドとライセンス表記の定番英語フレーズ
ContributingセクションとLicenseセクションは、OSSプロジェクトへの参加ハードルを左右します。定番フレーズを使い回すことで、コミュニティに親しみやすい印象を与えられます。
- 貢献歓迎: “Contributions are welcome! Feel free to open an issue or submit a pull request.”
- バグ報告: “Found a bug? Please open an issue with steps to reproduce.”
- PR歓迎: “Pull requests are always welcome. Please read CONTRIBUTING.md before submitting.”
- ライセンス表記: “This project is licensed under the MIT License. See the LICENSE file for details.”
- 行動規範: “Please note that this project is released with a Contributor Code of Conduct.”
API仕様書英語ライティング実践：開発者が迷わないエンドポイント記述の作法
API仕様書は、開発者が毎日参照するドキュメントです。曖昧な説明が1つあるだけで、実装ミスやサポート対応の増加につながります。伝わるAPI仕様書を書くには、文体・構造・情報の粒度を統一することが最重要です。このセクションでは、世界標準の書き方を具体例とともに解説します。
API仕様書で使う英語の文体：説明文・パラメータ記述・エラーメッセージの書き分け
API仕様書の英語には、箇所ごとに異なる文体ルールがあります。大きく3つのパートに分けて考えましょう。
- エンドポイント説明文：三人称単数現在形で書く（Retrieves / Creates / Deletes など）
- パラメータ説明：名詞句または短い文で書く。動詞は不要なことが多い
- エラーメッセージ：「何が起きたか」＋「どう直せばよいか」の2要素をセットで書く
エンドポイント説明文の構造：動詞選びと主語の統一
エンドポイントの説明文は、必ず三人称単数現在形の動詞で書き始めるのが世界標準です。主語（The endpoint / This API）は省略し、動詞から始めることで簡潔かつ統一感のある記述になります。
- Retrieves：リソースの取得（GET）
- Creates：リソースの新規作成（POST）
- Updates：リソースの更新（PUT / PATCH）
- Deletes：リソースの削除（DELETE）
- Returns：レスポンスの内容を説明する場面で使用
- Lists：複数リソースの一覧取得（GET + collection）
パラメータ・レスポンスフィールドの説明を簡潔に書くテンプレート
パラメータ説明には「型・必須/任意・デフォルト値・説明」の4要素を必ず盛り込みましょう。情報が欠けると開発者が推測で実装せざるを得なくなります。
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| user_id | string | Required | — | The unique identifier of the user. |
| limit | integer | Optional | 20 | The maximum number of items to return. Must be between 1 and 100. |
| status | string | Optional | “active” | Filters results by status. Accepted values: “active”, “inactive”. |
エラーメッセージ英語：開発者フレンドリーなエラー記述の原則
エラーメッセージは「何が起きたか」だけでなく、「どう直せばよいか」をセットで書くことで、開発者が問題を素早く解決できます。
| 評価 | エラーメッセージ例 | 問題点 / 改善点 |
|---|---|---|
| NG | Invalid request. | 何が無効なのか不明。開発者が原因を特定できない |
| NG | Error occurred. | 情報がなさすぎる。修正方法が一切わからない |
| OK | The `email` field is required. Provide a valid email address and retry. | 何が問題か＋修正方法が明確 |
| OK | The `limit` value must be between 1 and 100. Received: 200. | 受け取った値も示すことで即座に修正できる |
エラーメッセージの黄金律：「What went wrong（何が起きたか）」＋「How to fix it（どう直すか）」の2要素を必ずセットで記述すること。
リリースノート英語ライティング実践：変更内容を正確・簡潔に伝える構成術
リリースノートは、ユーザーが「自分のプロダクトに何が起きたか」を最初に確認するドキュメントです。業界標準の「KeepAChangelog」形式では、各行を過去形の動詞（Added / Fixed / Changed / Removed）で始めることがルールとして定着しています。この形式を採用するだけで、変更内容の一覧性と可読性が大幅に向上します。
リリースノートの標準セクション構成（New Features / Bug Fixes / Breaking Changes）
リリースノートは変更の種類ごとにセクションを分けて記述します。ユーザーは自分に関係する変更だけを素早く探せるため、セクション分けは必須です。
- Added：新機能・新エンドポイントの追加
- Fixed：バグ修正・不具合解消
- Changed：既存の動作・仕様の変更
- Removed：機能・パラメータの削除
- Deprecated：将来削除予定の非推奨化通知
各変更項目の英語1行要約：動詞の選び方と情報の優先順位
1行要約は「誰が・何を・なぜ（影響）」を30〜50語以内に凝縮するのが原則です。長すぎる説明や主語のない曖昧な文は避けてください。
| 種別 | 例文 |
|---|---|
| NG（長すぎ） | Fixed an issue that was causing the system to sometimes not correctly process requests when the user had not yet completed the onboarding flow and certain edge cases were triggered. |
| NG（曖昧） | Fixed some stuff related to login. |
| OK | Fixed a bug where users with unverified emails could not complete login on mobile devices. |
| NG（内輪用語） | Added support for the Phoenix pipeline in batch mode. |
| OK | Added batch processing support for the data export pipeline, reducing job completion time by up to 40%. |
Breaking Changesの書き方：ユーザーへの影響と移行手順を明確に伝える
Breaking Changesは、既存の実装を壊す可能性がある変更です。影響範囲・移行手順・非推奨タイムラインの3点を必ず明記し、ユーザーが具体的な行動を取れる情報を提供することが最重要です。
どのバージョン・どの機能を使っているユーザーが影響を受けるかを冒頭に示します。例：This change affects all users using API v2 authentication tokens.
旧仕様と新仕様を対比形式で記述します。例：Previously, the endpoint accepted both GET and POST. It now accepts POST only.
ユーザーが取るべきアクションを具体的に列挙します。例：To migrate: (1) Update your request method to POST. (2) Move query parameters to the request body.
旧仕様のサポート終了時期を記載します。例：The legacy endpoint will be fully removed in v4.0, scheduled for Q3.
リリースノートで避けるべき曖昧表現と内輪用語
社内スラング・コードネーム・未定義の略語は、外部ユーザーには意味が伝わりません。公開前に以下のチェックリストで確認しましょう。
- 社内プロジェクト名・コードネームを使っていないか
- 初出の略語に正式名称を添えているか（例：SSO → Single Sign-On (SSO)）
- 「improved」「enhanced」「various fixes」など効果が不明な曖昧語を使っていないか
- チームメンバーにしか伝わらないジャーゴンを排除したか
- 各行が標準動詞（Added / Fixed / Changed / Removed / Deprecated）で始まっているか
- Breaking Changesに影響範囲・移行手順・タイムラインの3点が揃っているか
「various improvements」「minor bug fixes」のような一括表現は、ユーザーが自分への影響を判断できないため避けてください。変更は必ず1項目1行で個別に記述するのが原則です。
ドキュメント品質を継続的に高める：レビュー・改善・習慣化のサイクル
良いドキュメントは、一度書いて終わりではありません。「書く→レビューされる→修正する」のサイクルを意識的に回すことが、長期的なドキュメント品質向上の唯一の近道です。このセクションでは、セルフレビューの方法からチームへの展開、AIツールの活用まで、実践的な改善サイクルを解説します。
セルフレビューで使える「5つの確認軸」チェックリスト
ドキュメントを書き終えたら、提出・公開の前に次の5軸でセルフチェックを行いましょう。慣れれば5分以内に完了できます。
- 能動態か：「The error is returned by the server.」より「The server returns an error.」が明確。受動態が続いていないか確認する
- 主語が明確か：「It processes the request.」の「It」が何を指すか、文脈から即座にわかるか確認する
- 用語が一貫しているか：「user」と「customer」、「endpoint」と「URL」を混在させていないか確認する
- 手順が番号付きか：操作手順は箇条書きではなく、必ず番号付きリストで記述されているか確認する
- 曖昧語がないか：「usually」「may」「some」「etc.」などの不明確な表現を使っていないか確認する
チームでドキュメント品質を統一するスタイルガイドの作り方
スタイルガイドは「完璧なものを最初から作ろう」とすると挫折します。最小構成から始めて、実際の課題が出るたびに追記していくのが現実的です。
- 用語集：プロダクト固有の単語と、使ってはいけない言い換え表現を対で記載する
- 表記ルール：数字・単位・大文字小文字の統一ルール（例: 「API key」か「API Key」か）
- 文体ルール：能動態優先・現在形を基本とするなどの方針
- 構成テンプレート：README・API仕様書・リリースノートそれぞれの雛形
最初は既存のドキュメントで「表記がバラバラだった箇所」を3〜5個ピックアップし、それをルール化するだけで十分です。チームのレビューコメントを蓄積する場所を1つ決め、そこをスタイルガイドに育てていくアプローチが最も継続しやすいです。
AIツールをドキュメント改善に活用する際の注意点と使い方
AIツールによる英語チェックは、誤字・文法ミスの検出や言い回しの改善候補を得るのに有効です。しかし、テクニカルライティングの原則を理解しないままAIの修正提案をすべて受け入れると、能動態を受動態に戻されたり、専門用語を一般的な語に置き換えられたりするリスクがあります。
AIツールはあくまで「最終確認の補助」として使うこと。ドキュメントの構造・用語の統一・情報の粒度はライター自身が判断する必要があります。
- AIツールはドキュメント作成にどこまで使っていいですか？
-
文法チェック・スペルミスの検出・言い回しの候補提示には積極的に活用して構いません。ただし、技術的な正確性や用語の一貫性はAIでは判断できないため、提案を鵜呑みにせず必ず内容を確認してから採用してください。
- スタイルガイドは何から始めればいいですか？
-
まず「今あるドキュメントで表記がバラバラな用語を3つ挙げる」ところから始めましょう。完璧なガイドを最初から作ろうとせず、チームのレビューで指摘された点を都度追記していくのが最も現実的です。
- セルフレビューだけで品質は上がりますか？
-
セルフレビューは出発点に過ぎません。他者からのレビューを受けることで、自分では気づけない曖昧さや構造の問題が明確になります。「書く→レビューされる→修正する」のサイクルを継続することが、最終的な品質向上につながります。
