technical-documentation

技術ドキュメント

Google のテクニカルライターのように、開発者向けドキュメントを監査、作成、改善します。まず読者のタスクから始め、すべての事実をコードと照合して確認し、その後、重要度の高い順にスタイルガイドを適用します。構成、文体、語句選びの順です。

基本原則

プロダクトの機能一覧ではなく、読者のタスクに合わせて書きます。 Google のガイドでは、ドキュメントを読む開発者はプロダクトに感心するためではなく、何かを成し遂げるために読んでいるため、親しみやすく、軽薄ではなく、正確で一貫性のある文章を求めています。以下のすべての指針の基盤となる、ガイドのルールを2つ紹介します。

• ガイドラインであり、ルールではありません。 内容を改善できる場合はガイドから外れてもかまいません。確立された専門用語を優先します。ただし、ドキュメント内では一貫性を保ちます。
• 優先順位。 プロジェクト独自のスタイルガイドを最優先し、次に Google のガイド、Merriam-Webster（スペル）、Chicago Manual of Style（一般的なスタイル）、Microsoft Writing Style Guide（技術的なスタイル）の順に従います。

ルールは2つの層に分かれています。構成と内容に関するルール（見出し、手順、コードサンプル、二人称、能動態、時代に左右されないドキュメント、アクセシビリティ）は、どの言語のドキュメントにも適用されます。[EN] のタグが付いたルール（スペル、シリアルカンマ、短縮形、単語リスト）は英語の文章にのみ適用されるため、他の言語では無視してください。また、依頼がない限り、ドキュメントを翻訳しないでください。

評価

目標：10/10。 スコアは、クイック診断の項目を通過した数です（全10項目、各1点。英語以外のドキュメントでは [EN] の項目は自動的に合格）。評価区分は、9～10 ならそのまま公開可能、7～8 なら語句と文体のみ修正、5～6 ならセクションを再構成してから再編集、4以下 ならドキュメント種別のひな形に沿って書き直しです。事実の誤りや確認不能、完了できない手順、画像にしか記載されていない情報、または代替テキストのない画像に含まれる情報といった重大な問題は、別の判定基準です。スコアにかかわらず、修正されるまでドキュメントは公開できません。スコア、不合格の項目、10/10にするための具体的な修正内容を報告してください。

フレームワーク

1. 読者とドキュメントの役割を把握する

基本概念： すべてのページは、1人の読者が1つのタスクを達成するためのものです。書き始める前に、読者とタスクの両方を明確にします。つまり、対象読者とそのレベル、読了後にできるようになることを定め、それに合ったドキュメント種別を選びます。チュートリアル（実践しながら学ぶ）、ハウツー（タスクを達成する）、コンセプト（仕組みを理解する）、リファレンス（情報を調べる）、README（概要を把握して使い始める）から選択します。

効果がある理由： 読者は自分のタスクに必要な情報を探します。コンセプト、手順、リファレンスが混在したページでは、目的の情報を見つけるためにすべてを読まなければなりません。

主なポイント：

• Google のテクニカルライティングコースでは、読者と対象範囲、対象外の範囲を明示してドキュメントを始めます。対象外の範囲を示すことで、別のページを探すべき読者を適切に案内できます。
• 「始める前に」には、前提条件をステップ1より前に記載します。ステップ4の中に含めるのではありません（慣例）。
• 重要なポイントを先に伝えます。導入では、プロダクトの歴史ではなく、読者が得られることを説明します。
• 手順ページの最後には、検証（「…を確認します」）と「次のステップ」を設けます（慣例）。

適用例：

コンテキスト	適用方法	例
README	概要を示す：内容、対象読者、3ステップでの開始方法、関連リンク	目的 → インストール → 初回実行 → ドキュメント一覧
複合ページ	コンセプトと手順を分けて、相互にリンクしたページにする	「OAuth の仕組み」と「OAuth の設定」
チュートリアルとハウツー	チュートリアルでは1つの経路を最初から最後まで学び、ハウツーでは前提知識があるものとします	「初めてのプラグインを作成する」と「フックを追加する」

ドキュメント種別を選択または再構成する際は、references/document-types.md を参照してください。README、スタートガイド、チュートリアル、ハウツー、コンセプトページのひな形、対象読者と範囲の説明、大規模なドキュメント群向けのセルフ編集手順を確認できます。

2. 声：読者に語りかけ、能動態で、現在形で、時代に左右されない表現にする

基本概念： 読者を「あなた」と呼び、すべての文で行為者を明示し、現在形で動作を説明します。また、5年後に読まれることを想定して書きます。

主なポイント：

• 「私たち」では誰が行動するのかが曖昧になり、「ユーザー」では読者を第三者にしてしまいます。どちらも指示を弱めます。
• 受動態が許されるのは、行為者が不明または重要でない場合のみです（「ファイルは保存時に暗号化されます」）。
• 「will」は本当に後で起きる結果にのみ使います。「サーバーは ack を送信します」とし、「送信する予定です」とはしません。
• 短縮形を使ってもかまいません。否定形では「is not」より「isn't」を Google は推奨しています [EN]。
• ソフトウェアは何かを望んだり、見たり、考えたりしません。「API が検出します」とし、「API が見ます」とはしません。
• 「please」は使いません（許可を求める場合に限ります）。「simply／easily／just」や最上級も使いません。手順が簡単なら、読者にもわかります。
• 時代に左右されない表現にします。「currently」「new」「soon」は削除し、未リリースの機能を予告してはいけません。

変更前 → 変更後：

• 「新しいダッシュボードは、ユーザーがログインすると簡単に表示されます。」→「サインインすると、ダッシュボードが表示されます。」
• 「トークンはクライアントによって更新することをお勧めします。」→「クライアントからトークンを更新します。」

ドキュメントの語調が適切でない、または一貫していない場合は、references/voice-and-words.md を参照してください。ガイドで定める例外、包括的で幅広い読者に配慮した表現、単語リスト全体を確認できます。

3. 文と単語

基本概念： 指示の前に条件を置き、1文につき1つの考えに絞り、ガイドの単語リストで推奨されている平易な単語を選びます。

主なポイント：

• 「ドキュメントを削除する場合は、Delete をクリックします」——読者は行動する前に、その手順が当てはまるかどうかを判断します。
• 略語は、初出時に正式名称を記し、括弧内に略称を添えます。URL や HTML など、誰もが知っている略語は省略してかまいません。
• ラテン語の略語は翻訳しづらく、読み取りの妨げになります。「e.g.」ではなく「たとえば」、「i.e.」ではなく「つまり」とし、「etc.」は省略するか、リストを最後まで書きます [EN]。
• 「can」は能力、「may」は許可、「might」は可能性を表します [EN]。
• 単語リストの例 [EN]：sign in（log in ではない）・動詞としての set up・lets you（allows you to ではない）・through または by using（via ではない）・after（once ではない）・use（leverage または utilize ではない）・checkbox・email
• 専門用語は、対象読者にとって適切なら問題ありませんが、それ以外の読者には欠点になります。定義するか、リンクを付けます。

変更前 → 変更後：

• 「すべてのフィールドに入力し終えたら、つまり、設定を保存するために Save をクリックします。」→「すべてのフィールドに入力したら、Save をクリックします。」
• 「CLI は、たとえば認証に GCP SDK を活用します。」→「CLI は、たとえば認証に Google Cloud SDK を使用します。」

単語の選び方を見直す場合は、references/voice-and-words.md を参照してください。単語リストの表（避ける表現 → 使う表現 → 理由）、略語のルール、助動詞を確認できます。

4. 構成：見出し、リスト、表、注意書き

基本概念： 構成は読者の道しるべです。文頭を大文字にした見出しは目次のように機能します。リストには、完全な文で導入される並列項目を並べます。表にはヘッダー行を設け、注意書きは必要な場合にだけ使います。

主なポイント：

• タスクの見出しは命令形のみ（「インスタンスを作成する」）。概念の見出しは名詞句（「インスタンスのライフサイクル」）にします。「〜ing」形の見出しは使いません
• リストの前にはコロンで終わる導入文が必要で、すべての項目を同じ文法形式にします。順序が重要な場合にのみ番号を付けます
• 用語と定義を組み合わせる場合は、2列の表より定義リストを使います
• 表にはヘッダー行と導入文を設け、結合セルや空のセルは使いません。スクリーンリーダーが正しく読み取るために必要です
• Note は役立つものの省略可能な情報、Caution は注意して進める必要がある場合、Warning は損害や取り消せない損失が生じる場合に使います。重ねて使わず、1つのセクションにつき最大1つを実用上の目安とします（推定）
• 相互参照には「参照してください」を使い、「上」や「下」は使いません。ページは再配置されたり翻訳されたりするためです
• リンクテキストにはリンク先の名前を記載します（「カスタムドメインを設定するを参照してください」）。「ここをクリック」は使いません
• 代替テキストには画像の目的を記載します。情報を画像だけに含めてはいけません

適用例：

文脈	適用方法	例
文章が長く続くページ	タスクが変わる箇所にタスクの見出しを挿入する	「インストール」「設定」「確認」
注意書きが3つ続く場合	2つは本文にまとめ、動作を変えるものだけ残す	データ損失に関する Caution を1つ
オプションの表	ヘッダー行と導入文を設け、セル内の表現を統一する	「以下のフラグで出力を制御します：」

ページの構成を修正する際は、references/structure-and-formatting.md を参照してください。見出し、リスト、表、注意書き、相互参照、リンクテキスト、画像、数値、日付のルールを、修正前後の例とともに確認できます。

5. 手順とコード

基本概念： 手順は、1つの命令形の操作だけを記載した番号付きリストです。各手順では、操作する場所と期待される結果を示します。コードはコードフォントで記載し、コロンで終わる文で導入します。また、読者がリテラル値と取り違えないプレースホルダーを使います。

主なポイント：

• 各手順には操作を1つだけ記載します。省略可能な手順には「省略可能：」を付けます。手順が1つだけの場合は「1.」ではなく箇条書きにします
• サブステップには a、b、c を使います。あらゆる選択肢ではなく、最短の手順を説明します
• UI 要素名は画面上の大文字・小文字の表記に合わせて太字にします。マウス操作には「クリック」、タッチ操作には「タップ」、デバイスを問わない場合には「選択」を使います
• ファイル名、パス、コマンド、フラグ、パラメーター、値にはコードフォントを使います。製品名には使いません
• プレースホルダーには ALL_CAPS_WITH_UNDERSCORES を使い、<your-key> や YOUR_API_KEY は使いません。サンプルの直後に説明します（「PROJECT_ID を…に置き換えます」）
• コマンド構文では、[optional] は省略可能な項目、{a|b} は排他的な選択肢、... は繰り返し可能な引数を表します
• サンプルは実行可能で最小限にし、80文字で折り返して、期待される出力を示します

修正前 → 修正後：

• 「キーを使って次のコマンドを実行します：shipit deploy --key=<your-key>」→「デプロイするには、次のコマンドを実行します：」→ フェンスで囲んだ shipit deploy --key=API_KEY →「API_KEY を Settings ページにあるキーに置き換えます。」
• 「1. デプロイするには、Deploy ボタンをクリックしてください。」→「1. Deploy をクリックします。ステータスが Deploying に変わります。」

手順やサンプルを作成する際は、references/procedures-and-code.md を参照してください。手順の全ルール、UI 要素とデバイスに応じた動詞、本文中のコード、プレースホルダー、コマンドライン構文、サンプルコードの品質チェックリストを確認できます。

6. リファレンスドキュメント：API、Docstring、CLI のヘルプ

基本概念： リファレンスの文章は、意図的に説明的で、漏れがなく、定型的です。読者は情報を調べるために参照するので、すべての項目が存在し、同じ形式で書かれている必要があります。

重要なポイント：

• すべての公開クラス、メソッド、フィールド、定数、列挙値を文書化します。項目が欠けていると、「サポートされていない」と受け取られます。
• メソッドの説明は、カテゴリに応じた動詞で始めます。「Gets the…」「Sets the…」「Checks whether…」「Creates a…」「Returns…」のように書き、「This method…」とは書きません。
• ブール値以外のパラメーターの説明は「The…」または「A…」で始めます。ブール値は、動作を表す場合は「If true, … If false, …」、状態を表す場合は「True if …; false otherwise」とします。
• 戻り値や例外があるメソッドでは、戻り値と例外（「Thrown when…」）をすべて文書化します。
• 非推奨の要素は、最初の文で置き換え先を示します。
• CLI の --help（Google には --help ページがないため、これは慣例です）：使用方法を [optional] 形式で記載し、概要を1行で示します。すべてのフラグを同じプレースホルダー形式で説明します。

変更前 → 変更後：

• 「This method is used for getting the customer.」 → 「Gets the customer for the given customerId. Throws NotFoundError when no customer exists.」
• 「@param force - force flag」 → 「@param force If true, deletes the bucket even if it contains objects. If false, fails when the bucket isn't empty.」

リファレンス資料を作成または監査する際は、references/api-reference.md を参照してください。動詞とカテゴリの対応表、パラメーター・戻り値・例外の記述パターン、JSDoc の完全な例を1つ、CLI ヘルプの慣例を確認できます。

7. リリースノート、変更履歴、移行ガイド

基本概念： 変更履歴は、これからアップグレードしようとしている読者のためのドキュメントです。各項目では、何が変わったか、それが読者にとって何を意味するか、何をすべきかを、Keep a Changelog の構成とほかのドキュメントと同じ語調で説明します。

重要なポイント：

• 最新バージョンを先頭にし、最上部に Unreleased セクションを置き、バージョン見出しに ISO 形式の日付を含め、差分へのリンクを付けます（Keep a Changelog）。
• 項目は Added／Changed／Deprecated／Removed／Fixed／Security に分類します。コミットメッセージをそのまま貼り付けてはいけません。
• 破壊的変更はバージョン内の先頭に記載し、移行手順へのリンクを付けます（慣例）。
• 非推奨の項目には、置き換え先と削除されるバージョンまたは日付を記載します。
• 移行ガイドは手順書です。「Before you begin」（バージョン、バックアップ）、変更前／変更後のスニペットを含む番号付き手順、「Verify the migration」、ロールバックを記載します。
• 各項目に Google の方針を適用します。操作は二人称で表現し、「currently／new」は使わず、フラグと API はコード書体にし、時制を統一します。

変更前 → 変更後：

• 「Various improvements to the auth module (#412)」 → 「Changed: login() now returns a Session instead of a token string. Update callers that read .token — see Migrate to sessions.」

リリースノートや移行ガイドを作成する際は、references/release-notes.md を参照してください。Keep a Changelog のひな形、カテゴリごとの項目の書き方、非推奨の表現、移行ガイドの手順を確認できます。

8. 監査、改善、または執筆の実施

基本概念： 3 つのモードに共通する規律は、インテーク → ローカルの規約 → 読者の視点で読む → 事実を確認する → 重大度順にルールを適用する → 定められた形式で出力することです。

手順：

1. インテーク。 モード（監査、改善、執筆）、文書の種類、読者とレベル、言語を確認します。執筆の場合、読者のタスクと事実の情報源（コードパス、既存ドキュメント）は必須です。確認できるまで始めないでください。
2. ローカルのスタイルガイド。 CONTRIBUTING.md、STYLE.md、docs/style-guide.md、.vale.ini と、既存ドキュメントが従っている規約（たとえば、どこでも「log in」を使うなど）を確認します。これらは Google より優先されます。プロジェクトがリンターを希望する場合、Google パッケージを使用する Vale で [EN] の単語と句読点のレイヤーを自動化できます。
3. 監査または改善の作業に入る前に、references/audit-checklist.md を読んでください。指摘事項で参照するルール ID はそこに記載されています。読んでいない ID を参照してはいけません。
4. 対象読者の視点で先入観なくドキュメントを読み、その後、スタイルを評価する前に、すべてのコマンド、フラグ、パラメーター、動作をコードと照合します。見栄えのよい誤ったドキュメントは、見栄えの悪い正しいドキュメントよりも問題です。
5. 重大度順にルールを適用します： ブロッキング → 高（構成、アクセシビリティ、参照項目の不足）→ 中（文体、注意書き、導入文）→ 低（単語リスト、句読点 [EN]）。
6. 出力。 指摘箇所は、読者が見つけられるようにします。見出しのパスを示し、ファイルを監査する場合は行番号も記載します。改善の場合は、1 行の Score before → after、書き換え後のドキュメント全文、続いて ## Change log の表（変更 | ルール ID と名前 | 理由）を出力します。事実は変更しません。元のドキュメントに記載されている事実はユーザーから提供されたものとして扱うため、保持してください（コードで確認できない場合は TODO(verify): … を付けます）。執筆の場合は、すべての不足箇所に TODO(verify) を付けたドキュメントを出力します。コードで確認できない、またはユーザーから提供されていないコマンド、フラグ、パラメーターは、決して含めないでください。

監査の出力は、必ず次の形式にしてください：

# Documentation Audit: [path or title]
**Score:** X/10 — [band]   **Shippable:** yes | no (blocking findings below)
**Diagnostic:** N/10 — failed rows: [row numbers + one-line reason each]
**Doc type / reader:** [type] for [audience, level]   **Language:** [en | xx — [EN] rules skipped]
**Local style guide:** [file found and honored | none — Google applies]
**Blocking:** [wrong/unverifiable facts, unfollowable steps, image-only information — or "none"]
**Findings:**
| # | Location | Rule (ID + name) | Before | After | Severity |
**Rewrite plan:** [ordered: structure → voice → words; what to do first to reach 10/10]

監査または書き換えを行う際は、references/audit-checklist.md を参照してください。ID と重大度を記載したルール表全体、重大度の基準、英語以外の言語の扱い、Vale の設定、監査例が掲載されています。

よくある間違い

間違い	問題となる理由	修正方法
読者のタスクではなく機能別に構成する	読者が 1 つのワークフローを探すために複数のセクションを行き来することになります	読者のタスクを明示し、ドキュメントの種類を選び、1 ページにつき 1 つのタスクを扱います
事実の確認より先にスタイルを直す	洗練された誤った手順は、より長く信頼されてしまいます	まず、すべてのコマンドとパラメーターをコードと照合します
「ここをクリック」や「下記を参照」	文脈がない場合、スクリーンリーダーで読む場合、または表示が折り返された後には意味が伝わりません	リンクテキストにリンク先を示し、相互参照には「参照」を使います
手順が段落に埋もれ、受動態や未来形になっている	読者が誰が何をするのか、またどの順番で行うのかを把握できません	命令形の番号付き手順にし、条件を先に示して現在形を使います
Note／Warning の枠を重ねて使う	すべてが強調され、何も伝わらなくなります	セクションごとに注意書きを 1 つにし、ほかの情報は本文にします
<your-key> や YOUR_API_KEY のようなプレースホルダー	読者が括弧まで入力したり、接頭辞をそのままの文字列として解釈したりします	大文字の API_KEY を使い、例の後で説明します
「スタイルを直す」過程で意味を書き換える	レビュー担当者は文章を承認しても、誤った動作を公開してしまいます	事実は変更せず、不明な点は TODO(verify) にします

クイック診断

質問	いいえの場合	対応
最初の段落に、対象読者と、この文書を読んでできるようになることが書かれていますか？	読者は自分に適したページか判断できません	対象読者、得られる成果、対象外の内容を追加します
文書の種類は、読者の目的（チュートリアル・ハウツー・概念・リファレンス・README）に合っていますか？	概念と手順が入り交じり、必要な情報が見つかりません	種類ごとに分け、ページ間をリンクします
すべてのコマンド、フラグ、パラメーター、動作は、コードまたはユーザーに照らして検証されていますか？	文書に誤った内容が記載されています	検証するか、TODO(verify) と記します。修正されるまで公開できません
見出しを読むと、文の形式で目次として機能しますか（タスクは命令形、概念は名詞句）？	ざっと読んでも内容を把握できず、「〜すること」という見出しでは具体的な操作がわかりません	見出しを書き直し、新しいタスクが始まる箇所に見出しを追加します
手順はすべて番号付きで、各項目に命令形の操作を1つずつ記載し、条件を先に示していますか？	読者が手順を見落としたり、確認する前に操作したりします	段落を手順に変え、条件を前に移動します
すべてのコードサンプルにコロンで終わる導入文があり、ALL_CAPS のプレースホルダーが説明されていますか？	読者が文字列をそのまま貼り付けたり、サンプルの目的がわからなかったりします	導入文を追加し、プレースホルダーを修正して説明します
テキストは二人称、能動態、現在形で、please／simply／just や擬人化表現を使っていませんか？	説明がナレーションのように聞こえます	文ごとに書き直し、冗長な表現を削除します
リンクは内容がわかる表現で、相互参照は「参照してください」形式、画像には代替テキストがあり、表には見出しがありますか？	スクリーンリーダーやリフロー表示でページが正しく表示されません	それぞれ修正し、画像だけで伝えている情報はテキストに移します
「現在」「新しい」「近日公開」などの表現や未発表機能がなく、時期に依存しない内容になっていますか？	公開したその日から文書が古くなります	時期を示す言葉を削除し、リリース済みの動作だけを説明します
[EN] 単語リスト、シリアルコンマ、短縮形、アメリカ英語のスペル（または各地域のガイド）に従っていますか？	細かな不統一が信頼を損ねます	単語リストを適用し、設定されている場合は Vale を実行します

出典について

Google の開発者向けドキュメントスタイルガイドは、Google のテクニカルライターが developers.google.com、Android、Google Cloud のドキュメント向けに管理している公開スタイルガイドです。関連する Technical Writing One および Two コースは、Google 社内のエンジニア研修として作成され、一般公開されています。このスキルは、CC BY 4.0（Google のサイトポリシーに基づく）のもとで両者を応用し、リリースノート向けに Keep a Changelog を追加したものです。これは独自の応用であり、Google の承認を受けたものではありません。

参考資料

• Google Developer Documentation Style Guide — まず Highlights と Word list をご覧ください
• Technical Writing One と Technical Writing Two — 言葉、文書、セルフエディット、サンプルコードに関する Google のコースです
• Keep a Changelog — このスキルがリリースノートに使用する変更履歴の構成です
• Jared Bhatti、Zachary Sarah Corleissen、Jen Lambourne、David Nunez、Heidi Waterhouse 著、"Docs for Developers: An Engineer's Field Guide to Technical Writing"
• Mark Baker 著、"Every Page Is Page One: Topic-Based Writing for Technical Communication and the Web"