このページは Cloud Translation API によって翻訳されました。

Bazel ドキュメントスタイルガイド

Bazel のドキュメントにご協力いただき、ありがとうございます。これは、最初のドキュメントスタイルガイドとしてご利用いただけます。このガイドで回答が見つからない場合は、Google デベロッパー向けドキュメントのスタイルガイドをご覧ください。

原則の定義

Bazel のドキュメントは、次の原則を遵守する必要があります。

簡潔。できる限り少ない単語を使用します。
クリア。わかりやすい言葉を使う。小学 5 年生向けの読解レベルには専門用語を使わずに書いてください。
整合性。ドキュメント全体で繰り返されているコンセプトには、同じ単語やフレーズを使用してください。
正解です。時間ベースの情報や将来について約束する作業は避けて、できるだけ長くコンテンツの品質が保たれるようにしましょう。

文章作成

このセクションでは、基本的な書き方のヒントを紹介します。

見出し

ページレベルの見出しは H2 から始まります。（H1 見出しはページタイトルとして使用されます）。
ヘッダーはできるだけ短くします。こうしてラップなしで TOC に収まります
- ○: 権限
- いいえ: 権限に関する簡単な説明
見出しでは文頭を大文字にする
- はい: ワークスペースを設定します。
- いいえ: ワークスペースを設定します
見出しはタスクベースまたは実用的なものにしてください。見出しが概念的なものである場合は、理解がベースになっていることもありますが、ユーザーの意図に沿って記述します。
- ○: グラフの順序を保持する
- いいえ: グラフの順序を保持します。

名前

Bazel や Starlark などの固有名詞は大文字にします。
- Yes: ビルドが終了すると、Bazel はリクエストされたターゲットを出力します。
- いいえ: ビルドの最後に、bazel はリクエストされたターゲットを出力します。
一貫性を保つ。既存のコンセプトに新しい名前を付けないでください。該当する場合は、用語集で定義されている用語を使用します。
- たとえば、ターミナルでコマンドを発行する場合、そのページでターミナルとコマンドラインの両方を使用しないでください。

ページスコープ

各ページには 1 つの目的を持たせ、最初にそれを定義する必要があります。これにより、読者は必要な情報をすばやく見つけることができます。
- ○: このページでは、Windows に Bazel をインストールする方法について説明します。
- いいえ: （導入の文章はありません。）
ページの最後で、次に行うべきことを読者に伝えます。明確なアクションがないページには、類似の概念、例、その他の探索方法へのリンクを記載できます。

対象

Bazel のドキュメントでは、対象者は主にユーザー（Bazel を使用してソフトウェアをビルドするユーザー）を対象としています。

読み手を「あなた」として呼びかけます。（なんらかの理由で「あなた」を使用できない場合は、ジェンダーに中立的な表現を使用します）。
- ○: Bazel を使用して Java コードをビルドするには、JDK をインストールする必要があります。
- 可: Bazel で Java コードをビルドする場合は、JDK をインストールする必要があります。
- いいえ: Bazel で Java コードをビルドするユーザーは、JDK をインストールする必要があります。
対象読者が一般の Bazel ユーザーでない場合は、ページの最初またはセクションで対象読者を定義します。その他の対象には、メンテナンス担当者、コントリビューター、移行担当者などのロールが含まれます。
「私たち」を避けましょう。ユーザードキュメントには作成者がいません。実現できるのは何であるかをユーザーに伝えるだけです。
- はい: Bazel の進化に合わせて、コードベースを更新して互換性を維持する必要があります。
- いいえ: Bazel は進化を続けています。Google は Bazel に変更を加えますが、互換性がない場合があり、Bazel ユーザーによる変更が必要になる場合があります。

時間の経過

特定の日付（2022 年第 2 四半期）に言及したり、「現在」、「現在」、「近日中」などといった、時間的要素を表す用語は可能な限り避けてください。これらはすぐに古くなるため、将来の予測の場合は不正確になる可能性があります。代わりに、バージョンレベルを指定します（例: 「Bazel X.x 以降は <機能> をサポートしていますか、GitHub の問題のリンク）。

○: Bazel 0.10.0 以降はリモートキャッシュをサポートしています。
いいえ: Bazel は、まもなくリモートキャッシュに対応する予定です（おそらく 2017 年 10 月）。

Tense

現在形を使用する。明確にするためにどうしても必要な場合を除き、過去形や未来形は使用しないでください。
- Yes: Bazel は、このルールに準拠していない依存関係を検出するとエラーを発行します。
- いいえ: Bazel でこのルールに準拠していない依存関係が検出された場合、Bazel はエラーを発行します。
可能であれば、受動態（物体が主語によって作用する）ではなく、能動態（主語が物体に作用する）を使用します。一般的に、能動態では誰に責任があるのかがわかるため、文章が明確になります。能動態を使用すると明瞭さが損なわれる場合は、受動態を使用します。
- Yes: Bazel は X を起動し、その出力を使用して Y をビルドします。
- いいえ: X が Bazel によって開始され、その後、出力を使用して Y がビルドされます。

トーン

ビジネスフレンドリーな口調で書いてください。

口語的な言葉は避ける。英語に固有のフレーズを翻訳するのが難しくなります。
- はい: 適切なルールセット
- いいえ: 適切なルールセットとは何でしょうか。
過度にフォーマルな言葉は避ける。テクノロジーに興味はあるものの、詳細を知らない人にコンセプトを説明するかのように記述します。

形式

ファイル形式

読みやすくするために、行は 80 文字で折り返します。長いリンクやコードスニペットは長くなる可能性がありますが、新しい行から始める必要があります。次に例を示します。

リンク

「こちら」や「以下」ではなく、わかりやすいリンクテキストを使用します。これにより、ドキュメントをスキャンしやすくなり、スクリーンリーダーに適しています。
- ○: 詳しくは、[Bazel のインストール] をご覧ください。
- いいえ: 詳しくは [こちら] をご覧ください。
可能であれば、リンクで文を終了します。
- ○: 詳しくは、[link] をご覧ください。
- いいえ: 詳しくは [link] をご覧ください。

順序付きリストを使用して、ステップでタスクを達成する方法を記述する
タスクベースではないことをリストするには、順序なしリストを使用します。（アルファベット順や重要度など、並べ替え順は必要です）。
並列構造で記述します。例:
1. すべてのリスト項目を文にします。
2. 同じ時制の動詞から始めます。
3. 従うべき手順がある場合は、順序付きリストを使用します。

プレースホルダ

ユーザーが変更する必要がある変数は山かっこで囲みます。マークダウンで、山かっこをバックスラッシュでエスケープします（\<example\>）。
- はい: bazel help <command>: <command> のヘルプとオプションを出力します。
- いいえ: bazel help command: 「command」のヘルプとオプションを出力します。
特に複雑なコードサンプルの場合は、コンテキストに適したプレースホルダを使用します。

コード

コードサンプルはデベロッパーにとっての強い味方です。記述方法はご存じだと思いますがここでヒントをいくつかご紹介します

小さなコードスニペットを参照する場合は、それを文に埋め込むことができます。コマンドのコピーなど、リーダーにコードを使用させたい場合は、コードブロックを使用します。

コードブロック

広告は短くしましょう。コードサンプルから冗長なテキストや不要なテキストをすべて削除します。
Markdown で、サンプルの言語を追加してコードブロックのタイプを指定します。

```shell
...

コマンドと出力を異なるコードブロックに分離します。

インラインのコード形式

ファイル名、ディレクトリ、パス、小規模なコードにはコードスタイルを使用します。
斜体、「引用符」、太字の代わりに、インラインコードスタイルを使用します。
- はい: bazel help <command>: <command> のヘルプとオプションを出力します。
- いいえ: bazel help command: 「command」のヘルプとオプションを出力します。