Googleが開発者向け文書で使っていた英語スタイルガイドが社外に公開された（Googleブログ）。
URLはこちら：
Google Developer Documentation Style Guide
https://developers.google.com/style/
MicrosoftやIBMは自社の英語スタイルガイドを書籍（リンク：MS／IBM）として販売するしているし、Appleは公開（リンク）している。Googleもマテリアル・デザインの一部としてスタイルを公開してはいる（リンク）が、分量が少ないため、他社と比べるとどうしても見劣りした。
そのため、「開発者向け文書」を対象としてはいるものの、ある程度の規模のスタイルガイドが公開されたのは意義深い。
そこで今回は、同スタイルガイドの要点（highlight）のみについて読んでみたい。
Highlights
https://developers.google.com/style/highlights
◆Tone and content（トーンとコンテンツ）
・Be conversational and friendly without being frivolous.
→ 会話っぽく、親しみがある感じだが、軽すぎないように
いきなり非ネイティブにとって難しい…。ただいくつか具体例が挙げられている。例えば、
- すべての文を同じフレーズ（"You can ..."や"To do"）で始めない
- 本当に高揚するような状況以外では、感嘆符（!）は避ける
- 指示の文で「please」は不要
・Don't pre-announce anything in documentation.
→ 将来の機能や製品について書かない
これはコンテンツに関する内容だが、Google社内では重要だったのかもしれない。一般的なスタイルガイドとしてはあまり意味がない項目だと思われる。
・Use descriptive link text.
→ リンク先を説明するようなテキストにする
要するに「ここをクリック」みたいなのは避けよ、ということになる。だから本ブログ記事にある書き方もダメで「Appleは公開（リンク）している」ではなく「Appleは公開（Apple Style Guide）している」となる。
・Write accessibly.
→ アクセスしやすいよう書く
障がいのある人だけでなく、海外の（英語が母語でない）ユーザーや古いブラウザーを使っているユーザーにとってもアクセスしやすくするということらしい。
具体的には、文法や句読点を正しく使ったり、能動態や現在形を使ったり、スラングなどは避けたり、といった点が挙げられている。
・Write for a global audience.
→ 世界中の読者に向けて書く
翻訳されることを意識しながら書くということだ。例えば、短く明瞭な文を書く、一貫性を持たせる、略語を使わない、特定文化の色が濃すぎないようにする、といった点が挙げられている。最後のは、例えばタッチダウン（アメフト）やホームラン（野球）みたいな用語は、そのスポーツが普及していない国では理解されにくい、ということだ。
◆Language and grammar（言葉づかいと文法）
・Use second person: "you" rather than "we."
→ 二人称（you）を使って書く
読者をyouで指して書きましょうということのようだ。
・Use active voice; make clear who's performing the action.
→ 能動態を使う。行為者を明確にする
受動態を使うと行為者をぼかすことができる（例：The file can be downloaded.）が、可能な場面ではそれを明確にしましょう（例：You can download the file.）ことだ。
・Use standard American spelling and punctuation.
→ アメリカ式のスペルと句読点を使う
例えばcenter（米）とcentre（英）がある。ちなみにスタイルガイドに掲載されていたのが、英米で違うスペルの一覧（リンク）が興味深い。
・Put conditional clauses before instructions, not after.
→ 条件を表す節は、指示よりも先に書く
スタイルガイドに挙げられている例だと、
✕ Click Delete if you want to delete the entire document.
◯ To delete the entire document, click Delete.
となる。
これはテクニカル・ライティングでよく言われる点で、最初に指示「Click Delete」を書くと、いきなり削除してしまう人がいるとされるためだ。
・For usage and spelling of specific words, see the word list.
→ ある単語の使い方とスペルはWord listを参照
この語リストは非常に役に立ちそうだ。例えば「app」か「application」かで迷ったら、ページ内検索すると「appを使う」と出てくる。ほかも、deselectは使わず「clear」にする、disableは使わず「turn off」にする、といった項目がある。
◆Formatting, punctuation, and organization（書式、句読点、構成）
・Use sentence case for document titles and section headings.
→ 文書のタイトルとセクション見出しでは、センテンス・スタイル（sentence case：最初の単語のみキャピタリゼーション）にする
キャピタリゼーションとは、単語の最初の文字だけ大文字にすること。
つまり、上記の例は、
✕ To Send a Message to Other Users
◯ To send a message to other users
ということになる。
ちなみに✕の例文（タイトル・スタイルとも）でも、aとtoは小文字になっている。タイトル・スタイルでキャピタリゼーションする場合も、冠詞や短い前置詞などは小文字のままになるというルールがある。
・Use numbered lists for sequences.
・Use bulleted lists for most other lists.
→ 手順では数字のリストを使う
→ それ以外のほとんどのリストではブレット（中黒）を使う
列挙する際に数字を使うのは、何かしら順番があるものだけにしましょうということ。テクニカル・ライティングでは一般的に知られている手法だ。
・Use description lists for pairs of related pieces of data.
→ 関連するデータのグループには、説明的なリストを使う
頭に数字、アルファベット、ブレットは無しで、名前そのものを列挙しましょうということのようだ。
・Use serial commas.
→ シリアル・カンマを使う
シリアル・カンマとは、3つ以上の項目をorやandで列挙する場合、最後の項目の前にカンマを置く方法だ。
✕ A, B, C and D
◯ A, B, C, and D
実はこのシリアル・カンマは英語圏で熱い論争がある（ウィキペディア英語版のSerial comma）。何か月か前には、シリアル・カンマが判決を左右したというニュースもあった。
・Put code-related text in code font.
→ ソースコードにはコード用フォントを使う
開発者向け文書ではソースコードが頻出するため、通常のテキストと見分けやすくするためだと推測できる。
・Put UI elements in bold.
→ UI要素にはボールドを使う
例えばボタン名やメニュー名について、角カッコ（[Edit]）や引用符（"Edit"）を使うのではなく、ボールド（Edit）にするということだ。
・Use unambiguous date formatting.
→ 曖昧さのない日付形式を使う
「月名 日, 年」という形式を使い、月名はスペルアウトするとしている。例えば「September 10, 2017」で、Sepみたいな略も避ける。
アメリカとイギリスでは月と日の順番が逆になり、「08/09/2017」みたいな書き方は8月9日なのか9月8日なのか分からないことがある。
◆Images（画像）
・Use SVG files or crushed PNG images.
→ SVGファイルか圧縮PNG画像を使う
・Provide alt text.
→ alt属性にテキストを入れる
・Provide high-resolution images when practical.
→ 高解像度の画像が役立ちそうであれば使う
要点（highlights）は、細かなルールというより、書く際の姿勢みたいな内容も入っている。
長文の英語は書かないものの、UIのボタン名あたりを書くエンジニアであれば「Word list」でページ内検索をかけて確認する程度の使い方でも有用かもしれない。
URLはこちら：
Google Developer Documentation Style Guide
https://developers.google.com/style/
MicrosoftやIBMは自社の英語スタイルガイドを書籍（リンク：MS／IBM）として販売するしているし、Appleは公開（リンク）している。Googleもマテリアル・デザインの一部としてスタイルを公開してはいる（リンク）が、分量が少ないため、他社と比べるとどうしても見劣りした。
そのため、「開発者向け文書」を対象としてはいるものの、ある程度の規模のスタイルガイドが公開されたのは意義深い。
そこで今回は、同スタイルガイドの要点（highlight）のみについて読んでみたい。
Highlights
https://developers.google.com/style/highlights
◆Tone and content（トーンとコンテンツ）
・Be conversational and friendly without being frivolous.
→ 会話っぽく、親しみがある感じだが、軽すぎないように
いきなり非ネイティブにとって難しい…。ただいくつか具体例が挙げられている。例えば、
- すべての文を同じフレーズ（"You can ..."や"To do"）で始めない
- 本当に高揚するような状況以外では、感嘆符（!）は避ける
- 指示の文で「please」は不要
・Don't pre-announce anything in documentation.
→ 将来の機能や製品について書かない
これはコンテンツに関する内容だが、Google社内では重要だったのかもしれない。一般的なスタイルガイドとしてはあまり意味がない項目だと思われる。
・Use descriptive link text.
→ リンク先を説明するようなテキストにする
要するに「ここをクリック」みたいなのは避けよ、ということになる。だから本ブログ記事にある書き方もダメで「Appleは公開（リンク）している」ではなく「Appleは公開（Apple Style Guide）している」となる。
・Write accessibly.
→ アクセスしやすいよう書く
障がいのある人だけでなく、海外の（英語が母語でない）ユーザーや古いブラウザーを使っているユーザーにとってもアクセスしやすくするということらしい。
具体的には、文法や句読点を正しく使ったり、能動態や現在形を使ったり、スラングなどは避けたり、といった点が挙げられている。
・Write for a global audience.
→ 世界中の読者に向けて書く
翻訳されることを意識しながら書くということだ。例えば、短く明瞭な文を書く、一貫性を持たせる、略語を使わない、特定文化の色が濃すぎないようにする、といった点が挙げられている。最後のは、例えばタッチダウン（アメフト）やホームラン（野球）みたいな用語は、そのスポーツが普及していない国では理解されにくい、ということだ。
◆Language and grammar（言葉づかいと文法）
・Use second person: "you" rather than "we."
→ 二人称（you）を使って書く
読者をyouで指して書きましょうということのようだ。
・Use active voice; make clear who's performing the action.
→ 能動態を使う。行為者を明確にする
受動態を使うと行為者をぼかすことができる（例：The file can be downloaded.）が、可能な場面ではそれを明確にしましょう（例：You can download the file.）ことだ。
・Use standard American spelling and punctuation.
→ アメリカ式のスペルと句読点を使う
例えばcenter（米）とcentre（英）がある。ちなみにスタイルガイドに掲載されていたのが、英米で違うスペルの一覧（リンク）が興味深い。
・Put conditional clauses before instructions, not after.
→ 条件を表す節は、指示よりも先に書く
スタイルガイドに挙げられている例だと、
✕ Click Delete if you want to delete the entire document.
◯ To delete the entire document, click Delete.
となる。
これはテクニカル・ライティングでよく言われる点で、最初に指示「Click Delete」を書くと、いきなり削除してしまう人がいるとされるためだ。
・For usage and spelling of specific words, see the word list.
→ ある単語の使い方とスペルはWord listを参照
この語リストは非常に役に立ちそうだ。例えば「app」か「application」かで迷ったら、ページ内検索すると「appを使う」と出てくる。ほかも、deselectは使わず「clear」にする、disableは使わず「turn off」にする、といった項目がある。
◆Formatting, punctuation, and organization（書式、句読点、構成）
・Use sentence case for document titles and section headings.
→ 文書のタイトルとセクション見出しでは、センテンス・スタイル（sentence case：最初の単語のみキャピタリゼーション）にする
キャピタリゼーションとは、単語の最初の文字だけ大文字にすること。
つまり、上記の例は、
✕ To Send a Message to Other Users
◯ To send a message to other users
ということになる。
ちなみに✕の例文（タイトル・スタイルとも）でも、aとtoは小文字になっている。タイトル・スタイルでキャピタリゼーションする場合も、冠詞や短い前置詞などは小文字のままになるというルールがある。
・Use numbered lists for sequences.
・Use bulleted lists for most other lists.
→ 手順では数字のリストを使う
→ それ以外のほとんどのリストではブレット（中黒）を使う
列挙する際に数字を使うのは、何かしら順番があるものだけにしましょうということ。テクニカル・ライティングでは一般的に知られている手法だ。
・Use description lists for pairs of related pieces of data.
→ 関連するデータのグループには、説明的なリストを使う
頭に数字、アルファベット、ブレットは無しで、名前そのものを列挙しましょうということのようだ。
・Use serial commas.
→ シリアル・カンマを使う
シリアル・カンマとは、3つ以上の項目をorやandで列挙する場合、最後の項目の前にカンマを置く方法だ。
✕ A, B, C and D
◯ A, B, C, and D
実はこのシリアル・カンマは英語圏で熱い論争がある（ウィキペディア英語版のSerial comma）。何か月か前には、シリアル・カンマが判決を左右したというニュースもあった。
・Put code-related text in code font.
→ ソースコードにはコード用フォントを使う
開発者向け文書ではソースコードが頻出するため、通常のテキストと見分けやすくするためだと推測できる。
・Put UI elements in bold.
→ UI要素にはボールドを使う
例えばボタン名やメニュー名について、角カッコ（[Edit]）や引用符（"Edit"）を使うのではなく、ボールド（Edit）にするということだ。
・Use unambiguous date formatting.
→ 曖昧さのない日付形式を使う
「月名 日, 年」という形式を使い、月名はスペルアウトするとしている。例えば「September 10, 2017」で、Sepみたいな略も避ける。
アメリカとイギリスでは月と日の順番が逆になり、「08/09/2017」みたいな書き方は8月9日なのか9月8日なのか分からないことがある。
◆Images（画像）
・Use SVG files or crushed PNG images.
→ SVGファイルか圧縮PNG画像を使う
・Provide alt text.
→ alt属性にテキストを入れる
・Provide high-resolution images when practical.
→ 高解像度の画像が役立ちそうであれば使う
要点（highlights）は、細かなルールというより、書く際の姿勢みたいな内容も入っている。
長文の英語は書かないものの、UIのボタン名あたりを書くエンジニアであれば「Word list」でページ内検索をかけて確認する程度の使い方でも有用かもしれない。
