英文スタイルガイド解説(4):リストの使い方1

本記事は「プログラミング英語検定ニュースレター #4」(2020年2月19日発行)からの一部抜粋です。同ニュースレターでは、検定の最新情報や英語解説を定期的に発信しています。登録はこちらから。


Googleが公開している開発者向け英文スタイルガイドから項目を1つ取り上げて紹介します。スタイルガイドは基本的には書く際に利用されますが、読む際にも参考になります。

今回は、情報を見やすく整理するリストの使い方に関する第1回目です。

リストの使い方(1)

URL:https://developers.google.com/style/lists (アクセス:2020-02-18)

同スタイルガイドでは、リストの種類として以下の5つを挙げています。

番号リスト

順に実行する手順で使う。

例:

Here’s a sequence of steps to follow:
  1. Open the box.
  2. Remove the bobcat from the box.
  3. Feed the bobcat.

使うHTML要素:ol、li

文字リスト(アルファベット大文字)

選択肢(とりわけ択一)を示すのに使う。

例:

A. Java
B. JavaScript
C. Go
D. Dart

使うHTML要素:ol(”upper-alpha”)、li

中黒リスト

順序でも選択肢でもないもので使う。

例:

Here’s a list of things that can go wrong, in no particular order:
  ・Your bicycle might explode.
  ・The sun might go out.
  ・An ant might break its leg and require a tiny splint.

使うHTML要素:ul、li

説明リスト

用語と、その定義や解説というセットに使う(用語集)。

例:

Here are some descriptions of types of birds:
Emu
    The best kind of bird.
Crow
    The other best kind of bird.
Peacock
    Also the best kind of bird.
Phoenix
    An even better kind of bird.

使うHTML要素:dl、dt、dd

見出し中黒の説明リスト

スペースを節約しつつ、用語+定義などのセットに使う。見出しはボールド。

例:

Here are some descriptions of types of birds:
  ・Emu. The best kind of bird.
  ・Crow. The other best kind of bird.
  ・Peacock. Also the best kind of bird.
  ・Phoenix. An even better kind of bird.

使うHTML要素:ul、li


なお、項目を見やすく提示する方法としては「リスト」のほかに「テーブル」があります。どちらを使うかの判断基準として以下が挙げられています(リンク。2020-02-18アクセス)。

・各項目が1つのまとまり。例:プログラミング言語名一覧、手順
  → 番号リスト、文字リスト、中黒リスト(ol、ul)
・各項目がペアのデータ。例:用語と定義
  → 説明リスト(dl)
・各項目が3つ以上のデータ
  → テーブル

(ライセンス表示: Portions of this page are modifications based on work created and shared by Google and used according to terms described in the Creative Commons 4.0 Attribution License.)

英文スタイルガイド解説(3):手順の書き方

本記事は「プログラミング英語検定ニュースレター #3」(2020年1月20日発行)からの一部抜粋です。同ニュースレターでは、検定の最新情報や英語解説を定期的に発信しています。登録はこちらから。


Googleが公開している開発者向け英文スタイルガイドから項目を1つ取り上げて紹介します。スタイルガイドは基本的には書く際に利用されますが、読む際にも参考になります。

今回は手順の書き方について、重要と思われるポイントをいくつか紹介します。

手順の書き方(Procedures)

URL:https://developers.google.com/style/procedures (アクセス:2020-01-19)

導入文

通常、手順の前に導入文を書きます。単に見出しを繰り返すのではなく、読者に状況を説明します。

導入文の直後に手順が来る場合、コロン(:)を使います。一方、導入文と手順と間に注などが入る場合、普通の文と同様にピリオド(.)で終えます。

導入文はそれ自体で完全な文の形にして書きます。

✕ To customize the buttons:
◯ To customize the buttons, follow these steps:

(◯は命令文として完全な文になっている)

ステップが1つの手順

ステップが1つだけの手順の場合、導入文の中に組み込みます。

✕ To clear (flush) the entire log, follow this step:
   1. Click Clear logcat.
◯ To clear (flush) the entire log, click Clear logcat.

操作が複数ある手順

一般的には、1つの操作に対してステップ1つとします。ただし細かな操作はまとめることが可能で、メニューの連続選択では「>」を使います。

◯ 1. Click File > New > Document.

その他のポイント

【A】まず目的を書いてから操作を書く(「節の順序」も参照)

✕ 1. Click File > New > Document to start a new document.
◯ 1. To start a new document, click File > New > Document.

例では「新規ドキュメントを始めるには」という目的が最初に置かれています。

【B】まず場所を書いてから操作を書く

✕ 1. Click File > New > Document in Google Docs.
◯ 1. In Google Docs, click File > New > Document.

例では「Google Docs」という場所が最初に置かれています。

【C】Pleaseは使わない

✕ 1. To open a document, please click File > Open.
◯ 1. To open a document, click File > Open.

英語の指示文では、pleaseなしの命令形が一般的です。

【D】省略可能な任意のステップでは最初に「Optional:」を付ける

◯ 1. Optional: Type an arbitrary string, to be delivered to the target address with each notification delivered over this channel.

【E】方向を示す言葉(例:above、below、right-hand side)で場所を指示しない。アクセシビリティーやローカリゼーション(翻訳)で問題が発生しうるため

たとえばアラビア語など文字を右から左に書く言語の場合、UI要素の配置位置も左右逆になります。そういった言語に翻訳されると、指示の場所が逆になります。

またパソコンとスマホで画面レイアウトが変わるようなレスポンシブなデザインでUIを作成した場合も同様の問題が発生する可能性がありそうです。

(ライセンス表示: Portions of this page are modifications based on work created and shared by Google and used according to terms described in the Creative Commons 4.0 Attribution License.)

英文スタイルガイド解説(2):日時の書き方

本記事は「プログラミング英語検定ニュースレター #2」(2019年12月20日発行)からの一部抜粋です。同ニュースレターでは、検定の最新情報や英語解説を定期的に発信しています。登録はこちらから。


Googleが公開している開発者向け英文スタイルガイドから項目を1つ取り上げて紹介します。スタイルガイドは基本的には書く際に利用されますが、読む際にも参考になります。

日時の書き方(Dates and times)

URL:https://developers.google.com/style/dates-times (アクセス:2019-12-19)

時刻

24時間での表記が要求されない限り、12時間での表記とします。

◯ 3:45 PM

このときの注意点は以下の通りです。

  • AMとPMは大文字にする
  • 時刻とAM(またはPM)との間に半角スペースを入れる

時間の幅はハイフンを使って「5-10 minutes」のように書きます。日本語では波かっこ(例:5〜10)を使うことがありますが、英語では使わないので注意しましょう。

日付

基本的に、月はスペルアウト(Janのように省略しない)し、年は2桁ではなく4桁で書きます。

◯ January 19, 2017

このような「月日年」の順序はアメリカ式です(イギリス式は「日月年」の順)。もし曜日を付ける場合は先頭に置いて「Sunday, February 12, 2017」とします。

月名や曜日名は省略しないのが基本です。たとえばMondayを「Mon」とはしません。ただし表のセルのようにスペースが限られている際に3文字での表記は可能です。その場合、先頭を大文字にし、末尾のピリオドは付けません。たとえばMondayなら「Mon」、Septemberなら「Sep」です。また3文字で略す場合は一貫してその表記にします。

✕ Mon, September 3, 2018(→ 省略とスペルアウトが混在)
◯ Mon, Sep 3, 2018

基本的に月名はスペルアウトして表記するとしていますが、数字のみで日付を書きたいケースがあります。このときはISO 8601に従って「yyyy-mm-dd」という形にします。

✕ 04/06/2017
◯ 2017-04-15

特に前者の「04/06/2017」のような書き方は、アメリカ式で読むかイギリス式で読むかで意味が変わってしまうため、避けた方がよいでしょう。

(ライセンス表示: Portions of this page are modifications based on work created and shared by Google and used according to terms described in the Creative Commons 4.0 Attribution License.)

英文スタイルガイド解説(1):節の順序

本記事は「プログラミング英語検定ニュースレター #1」(2019年11月15日発行)からの一部抜粋です。同ニュースレターでは、検定の最新情報や英語解説を定期的に発信しています。登録はこちらから。


Googleが公開している開発者向け英文スタイルガイドから項目を1つ取り上げて紹介します。スタイルガイドは基本的には書く際に利用されますが、読む際にも参考になります。

節を書く順序(Clause order)

URL:https://developers.google.com/style/clause-order

ユーザーに対して指示文を書く場合、先に指示ではなく、条件(条件節*)を書くようにします。
Googleではまず以下の例を挙げています。

✕ See [リンク] for more information.
◯ For more information, see [リンク].

いきなり「See …」と指示を書くのではなく、「詳細情報が必要なら」と条件をまず書きます。次の例も同様です。

✕ Click Delete if you want to delete the entire document.
◯ To delete the entire document, click Delete.

いきなり「Click Delete …」という指示ではなく、「文書全体を削除する場合には」と条件を書くようにします。

こうすると、ユーザーは条件に該当しなければ、全文を読む必要がありません。

また、先に指示を書いておくと、ユーザーは条件を読まないまま、すぐ指示を実行してしまう可能性があります。特に2つ目の例の場合、文書全体を削除するという重大な結果につながる恐れがあります。

*「節」とは、文の構成要素中で「主語+述語」がある部分のこと。

(ライセンス表示: Portions of this page are modifications based on work created and shared by Google and used according to terms described in the Creative Commons 4.0 Attribution License.)