Googleが公開している開発者向け英文スタイルガイドから項目を1つ取り上げて紹介します。スタイルガイドは基本的には書く際に利用されますが、読む際にも参考になります。
記事の英語難易度は「中〜上級」です。
マニュアルなどでは「注」や「警告」を書くことがあります。今回はそういった注意事項の書き方です。
URL： https://developers.google.com/style/notices （2022-6-26閲覧）
注意事項を書くケース
重要または有用な情報を提供する際、本文とは別に注意事項として掲示できます。ただし、ユーザーは自分に関連がなさそうな要素は読み飛ばすようです。そのため、注などとして載せるか迷う場合、まず本文にした後、本当に必要であれば別途注意事項にするとしています。
また、あまり注意事項が多いと目立たなくなるので、多用しすぎないようにします。
注意事項の種類
下記の「Note」、「Caution」、「Warning」、「Success」の4種類を使うとしています。
Note
補足やコツに使います。ユーザーにとって有用な情報で、重大とまでは行かない情報です。
▼Noteに記載される例文：（※以降、英文はすべてGoogle）
- Generating excessive amounts of traffic to external systems can resemble a denial-of-service attack.
- 外部システムに対して過度なトラフィックを送ると、DoS攻撃のようになる恐れがあります。
日本語だと「注」、「注意」、「注記」、「留意」、「メモ」、「補足」などの訳語が当てられます。ただし「注意」あたりだと次のCautionと訳語が重複するかもしれません。もしマニュアルを日英翻訳をするのであれば、訳語は事前に調整しておいた方がよいでしょう。
Caution
注意して進めるようユーザーに伝えるのに使います。
▼Cautionに記載される例文：
- We don’t recommend using a broad 0.0.0.0/0 range that would allow all traffic.
- あらゆるトラフィックが許可され得る、レンジの広い0.0.0.0/0を使うことは推奨されません。
日本語だと「注意」や「警告」といった訳語が使われます。やはり次のWarningの訳語と重複する恐れはあるので、事前調整は不可欠です。
Warning
cautionよりも強いニュアンスです。してはいけない操作や、元に戻せない恐れのある操作に使います。Warningを無視した場合、経済的な損害やセキュリティー違反といった結果を招く可能性があります。
▼Warningに記載される例文：
- Don’t put a password on the command line; doing so is a security risk.
- コマンドラインにパスワードを入力してはいけません。セキュリティー上のリスクがあります。
日本語だと「警告」、「注意」、場合によっては「危険」といった訳語になります。
Success
操作が成功した場合や、エラーがない状況で使います。インタラクティブなまたは動的なコンテンツで使い、静的なコンテンツでは使いません。
▼Successに記載される例文：
- You’ve successfully deployed an application to GKE.
- 正常にアプリケーションをGKEにデプロイしました。
Noteの使い方
使える条件
次に挙げる条件がすべて満たされる場合、「Note」を使うとしています。
- ユーザーの今の操作に関連しているが、必須ではない
- その時点で掲示してもユーザー操作を阻害しない
- 例えば、代替となるような操作手順を示す場合はNoteにしない
- 現在の情報の流れの一部ではない
- 単に後続手順、結果、追加情報ではない
使わないケース
Noteを使わないケースがいくつか挙げられています。
- 相互参照にはNoteを使わない
- ユーザーが満たしておくべき前提条件や手順の掲示にNoteを使わない
- こういった情報は前の手順とする
- 手順の1ステップ全体をNoteに入れない
- 正常に完了するのに必要な情報にNoteを使わない
- 続いているテキストの一部をNoteにしない
- 例えば、期待できる結果を示したり、前のステップを説明したりするのに使わない
見た目の例
特に組織でルールを決めていなければ、次のような見た目（HTMLの場合）が推奨されています。
（ライセンス表示： 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.）
[筆者紹介]
