google-doc-style

Google 開発者向けドキュメントのスタイル

Google Developer Documentation Style Guide の指針に沿って、読者向けの文章を書きます。知識のある友人のように、会話調で、直接的かつ正確に、世界中の読者に向けて書きます。このスキルでは、同ガイドの内容を要約しています。読者向けの文章（「適用範囲」を参照）では、以下の基本ルールに従ってください。個別の状況について詳しく知りたい場合は、リファレンスファイルを開いてください。

適用範囲

このスキルは、人が読む文章に適用されます。チャットの回答や解説、要約、レポート、README、ドキュメント、チュートリアル、ハウツーが対象です。単語リストによる置き換えは、こうした文章にのみ適用されます。識別子、フラグ、パス、プロジェクト内の引用語句には適用されません。

以下は変更しません。

• コード、識別子、文字列リテラル、コードコメントは、周囲のコードベースに合わせて記述します。
• コミットメッセージ、構成ファイル、機械生成の出力。
• そのまま報告する引用文、エラーメッセージ、コマンド出力。
• 機械解析される Markdown（たとえば AGENTS.md やその他のエージェント向け契約）。ファイルの既存の文体と構成に合わせ、公開ドキュメントのスタイルに変更しないでください。
• ツール呼び出しの引数。

ルールが競合する場合は、ユーザーによる明示的なスタイルの指定、環境上の制約（システムプロンプトで指定された回答の長さや形式など）、このスキルの順に優先します。このスキルが定めるのは、どのように書くかであり、どれだけ書くかではありません。環境で指定された簡潔さは保ってください。

文体とトーン

堅苦しすぎず、ふざけすぎない中間のトーンを目指します。知識のある友人のように、平易に説明し、気取った表現は避けてください。

• 一人称複数（「私たち」）ではなく、二人称（「あなた」）を使います。「ユーザー」は、読者のユーザーを指し、読者自身を指しません。ユーザーや環境によって異なる人称（チームや製品を主語にする「私たち」、定義されたペルソナ、法律文書での一人称など）が指定されている場合は、それに従います。
• 会話調でも、軽薄な表現は避けます。省略形は使えますが、スラング、誇張表現、ポップカルチャーへの言及、感嘆符は使いません。
• 「シンプル」「簡単」「手早い」「分かりやすい」といった表現は使いません。読者が難しいと感じた場合、問題が読者にあると思わせてしまいます。
• 指示文で「please」は使いません。「Save をクリックしてください」と書き、「Please click Save」とは書きません。
• 「let's」や、「note that」「as you can see」「at this time」のような埋め草表現は使いません。
• 時代に左右されない表現を使います。「currently」「new」「soon」「as of this writing」は使わず、今後の機能を事前に告知することも避けます。
• ソフトウェアを擬人化しません。サービスが「考える」「望む」「見る」とは表現せず、「確認する」「必要とする」「検出する」「返す」と表現します。
• 比喩、慣用句、専門用語の多用を避けます。第一言語が英語ではない読者にも伝わるように、専門用語を使わずに説明するか、初出時に定義します。
• 最上級や断定的な表現は使いません。「最高」「最速」「必ず」「決して」や、無条件のセキュリティ保証は避けます。

くだけすぎた表現: 「ガベージコレクションを実行すれば、あとは大丈夫です。」 適切な表現: 「クリーンアップするには、collectGarbage メソッドを呼び出します。」 堅苦しすぎる表現: 「ガベージコレクション機能の呼び出しは、次のように実行できます。」

文法の基本

• 能動態。 誰が何をするのかを明確にします。「サーバーが応答を送信します」とし、「応答が送信されます」とは書きません。
• 現在形。 「コマンドは一覧を返します」とし、「返す予定です」とは書きません。未来形は、実際に後で起こる出来事に限って使います。
• 手順の前に条件を示す。 「ドキュメントを削除するには、削除をクリックします」のように、目的や条件を先に示すことで、その手順が読者に当てはまるかどうかが分かります。
• 助動詞を正確に使う。 要件には「必須です」、選択肢には「できます」、可能性には「可能性があります」、推奨事項には「おすすめします」を使います。「べきです」「できるでしょう」「でしょう」「かもしれません」は避けます（ポリシーの場合を除きます）。
• アメリカ英語のスペルを使います（迷った場合は Merriam-Webster を参照します）。
• 短い文。 目安として約26語以内にし、段落ごとに1つの考えを述べ、要点を先に示します。
• 曖昧さをなくす補助語を残します。 「X の場合は、その後 Y を行います」「あなたが 定義した ルール」「プロファイラーを起動し、その後 アプリを実行します」のようにします。
• 略語は初出時に正式名称を併記します。「二要素認証（2FA）」のようにします。ただし、正式名称より略語のほうがよく知られている場合（API、URL、HTML）は除きます。「例：」「すなわち」「など」は使わず、「たとえば」「つまり」「〜のような」と書きます。

冠詞、大文字表記、短縮形、複数形、所有格、代名詞、主張、専門用語について詳しくは、references/grammar.mdをお読みください。

書式の基本

• すべての見出しとタイトルはセンテンスケースにします。 タスクの見出しは動詞の原形で始めます。「インスタンスを作成する」とし、「インスタンスの作成」とはしません。
• 手順には番号付きリスト、それ以外には箇条書きを使います。 各手順には命令形の操作を1つだけ記載します。すべてのリストは、コロンで終わる完全な文で導入し、各項目の形式をそろえます。
• シリアルカンマを使います。 「サーバー、プロキシ、ロードバランサー」。
• コードにはコードフォント（バッククォート）を使います。文中のコマンド、ファイル名、パス、API 名、パラメーター、リテラル値、HTTP ステータスコードが対象です。
• 太字は UI 要素にのみ使います。「デプロイをクリックします」のようにします。強調には使いません。
• 内容が分かるリンクテキストを使います。 対象の名前にリンクし、「ここをクリック」や文章中の URL をそのまま使うことは避けます。「詳細については、X をご覧ください」のようにします。
• 0から9まではスペルアウトし、10以上は数字で表します。単位を伴う数値はすべて数字で表します（「8ビット」「64 GB」のように、数値と単位の間にスペースを入れます）。
• 曖昧さのない日付を使います。 「2026年8月19日」または ISO 8601 形式（2026-08-19）とし、「8/19/26」は使いません。
• 重要な情報を伝えるセミコロンや括弧、「および／または」、文章中のスラッシュは避けます。 前後にスペースを入れない em ダッシュは、区切りとして使えます。
• 注記は必要な場合だけ使います。 すべての段落が注記だと、注記の重要性が薄れます。

見出し、リスト、手順、表、数字、日付、注記について詳しくは、references/formatting.mdをお読みください。句読点の細則（カンマ、ハイフン、ダッシュ、引用符）については、references/punctuation.mdをご覧ください。

用語の選び方

使用頻度の高い用語をいくつか紹介します。用語の一覧はreferences/word-list.mdにあります。適切な用語か迷ったときは、一覧を確認してください。

使用する表現	避ける表現
サインインする	ログインする／ログイン（動詞）
OKをクリックする	OKをクリックする（「に」を付ける）
〜できます	〜を許可します／〜を可能にします
使う	活用する／利用する
〜するために	〜する目的で
影響する（動詞）	インパクトを与える（動詞）
実行する	エグゼキュートする
停止する、終了する、キャンセルする	強制終了する／終了させる／中止する
以前／以降（ドキュメント、バージョン）	上／下、高い／低い
使って／通じて	経由して
〜なので	〜以来（原因を示す場合）
〜ですが	〜の間（対比を示す場合）
メール	Eメール
許可リスト／拒否リスト	ホワイトリスト／ブラックリスト

包括的でアクセシブルな文章

幅広い読者に伝わる文章を書きます。差別的な表現（「健全性チェック」ではなく「簡易チェック」）、性別を前提とする表現（単数の they を使います）、暴力的な比喩（「ハングする」ではなく「応答を停止する」）、包括性に欠ける用語（「マスター／スレーブ」ではなく「プライマリ／レプリカ」）は避けます。UI は位置や見た目ではなくラベルで示し、リンクテキストは文脈から切り離しても内容が分かるようにし、方向を示す表現（「上／下」ではなく「前述／後述」）は避けます。詳細はreferences/inclusive-accessible.mdをご覧ください。

コードとインターフェースについて書く

文章でコードや UI（プレースホルダー、コマンドライン構文、UI のナビゲーション、コードフォント・太字・斜体の使い分け）に言及する場合は、references/code-in-text.md に従ってください。特によく使うルールは次の 2 つです。

• コード項目を活用形にしないでください。「POST リクエストを送信する」とし、「データを POST する」とはしません。「Intent オブジェクト」とし、「Intents」とはしません。
• プレースホルダーには説明的な UPPERCASE_WITH_UNDERSCORES を使い、それぞれに「次の値を置き換えてください：」と説明を添えてください。foo や x は使わないでください。

作成したサンプル値は、実際の値ではありません。example.com、[email protected]、Example Organization、192.0.2.0/24、性別を限定しない名前（Alex、Dana、Quinn）を使います。ユーザーや環境からすでに提供された事実は、そのまま使用してください。サンプルデータに置き換えてはいけません。

セルフチェック

仕上げる前に、まず情報の混入がないか確認し、次に頻発するスタイル上の誤りを確認してください。

1. このスキルを読者向けの文章以外にも適用していませんか（「対象範囲」を参照）。該当する場合は、元に戻してください。
2. ユーザーや環境から提供された事実を、サンプルデータや例示データに置き換えていませんか。該当する場合は、実際の事実に戻してください。
3. 感嘆符、または「単に」「簡単」「簡単に」「ただ」「お願いします」「現在」という語句を使っていませんか。
4. タイトルケースの見出し、または -ing 動詞で始まる見出しを使っていませんか。
5. 行為者が明示されない受動態や、現在形でよい箇所に「will」を使っていませんか。
6. 読者が「あなた」であるにもかかわらず、ユーザーや環境の声でない箇所に「We」を使っていませんか。「should」を「must」または「can」にすべき箇所はありませんか。
7. コード、ファイル名、コマンドをコードフォントにしていませんか。強調に太字を使っていませんか。
8. シリアルコンマを省略していませんか。文章中に URL をそのまま記載していませんか。

出典表示

このスキルは、Google LLC が作成し、Creative Commons Attribution 4.0 License に基づいて使用されている Google Developer Documentation Style Guide を要約したものです。このガイドが基準です。このスキルとガイドの内容が異なる場合は、ガイドに従ってください。