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

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

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

原則の定義

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

簡潔。できる限り少なくしてください。
クリア分かりやすい言葉を使います。専門用語を使わずに 5 年生に向けて書いてください。
一貫性。ドキュメント全体で同じ単語やフレーズを使用します
正解です。時間ベースの情報や将来への約束を避けて、コンテンツができるだけ長く正確になるように記述します。

文章作成

このセクションでは、基本的な文章作成のヒントを紹介します。

見出し

ページレベルの見出しは下半期から開始します。（H1 の見出しはページのタイトルとして使用されます）。
ヘッダーはできるだけ短くしてください。こうすることで、ラップなしで TOC に収まります。
- はい: 権限
- いいえ: 権限に関する簡単な注意事項
見出しには文頭を大文字にします（アルファベットの場合）。
- はい: ワークスペースを設定します
- いいえ: ワークスペースを設定する
見出しは、タスクベースまたは実用的なものにしてください。見出しが概念的な場合は理解に基づいているかもしれませんがユーザーが何をするかを書きます
- ○: グラフの順序を保持する
- いいえ: グラフの順序を保持します。

名前

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

ページ範囲

各ページには 1 つの目的があり、最初にそれを定義する必要があります。これにより、読者は必要な情報を素早く見つけることができます。
- はい: このページでは、Windows に Bazel をインストールする方法について説明します。
- いいえ: （導入文はありません）。
ページの最後に、読者に次の手順を伝えます。明確なアクションがないページでは、同様のコンセプト、例、その他の調査方法へのリンクを記載できます。

対象

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

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

時間の経過

可能な限り、特定の日付（2022 年第 2 四半期）に言及したり、「現在」、「現在」、「近日中」などの言葉は使用しないようにします。これらはすぐに陳腐化し、将来の予測では不正確になる可能性があります。代わりに、バージョンレベルを指定します（「Bazel X.x 以降は <機能> をサポートしている」や GitHub の問題リンクなど）。

はい: Bazel 0.10.0 以降はリモートキャッシュをサポートしています。
いいえ: Bazel では、2017 年 10 月を予定しています。

Tense

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

トーン

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

話し言葉は避ける。英語に固有のフレーズは翻訳しづらいです。
- はい: 適切なルールセット
- いいえ: では、どうすればよいルールセットとは何でしょうか。
過度にフォーマルな表現は避ける。テクノロジーには興味はあるけれども詳細がわからない人にコンセプトを説明するように書いてください。

形式

File type

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

リンク

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

順序付きリストを使って、タスクの遂行方法をステップで説明する
タスクベースでないものを一覧表示するには、順序なしリストを使用します。（ただし、アルファベット順や重要度など、並べ替え順序が必要です）。
並列構造で記述する例:
1. リストアイテムの文をすべて文にします。
2. 同じ時制の動詞から始めます。
3. 手順を説明できる場合は順序付きリストを使用します。

プレースホルダ

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

コード

コードサンプルはデベロッパーにとって最も頼りになる存在です。コードの書き方はすでにご存じかと思いますがいくつかのヒントを紹介します

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

コードブロック

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

```shell
...

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

インラインコードのフォーマット

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