BazelCon 2024 登録の受け付けを開始しました。

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

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

7.3 · 7.2 · 7.1 · 7.0 · 6.5

Bazel のドキュメントにご協力いただき、ありがとうございます。これは、ドキュメントの作成を開始するための簡単なスタイルガイドです。このガイドで解決できないスタイルに関する質問については、Google デベロッパー向けドキュメントのスタイルガイドに沿って対応してください。

原則の定義

Bazel のドキュメントは、次の原則に従う必要があります。

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

文章作成

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

見出し

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

名前

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

ページスコープ

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

件名

Bazel のドキュメントでは、主な対象はユーザー（Bazel を使用してソフトウェアをビルドするユーザー）である必要があります。

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

時間の経過

可能であれば、特定の日付（2022 年第 2 四半期）を参照したり、「今すぐ」、「現在」、「まもなく」などの時間に関する用語を使用しないようにしてください。これらはすぐに古くなるため、将来の予測の場合は不正確になる可能性があります。代わりに、バージョンレベルを指定します（例: 「Bazel X.x 以降は <機能> をサポートしていますか、GitHub の問題のリンク）。

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

Tense

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

トーン

ビジネスに適したトーンで記入してください。

口語的な表現は避けてください。英語に固有のフレーズを翻訳するのが難しくなります。
- はい: 優れたルールセット
- いいえ: では、適切なルールセットとはどのようなものですか？
過度に堅苦しい表現は避けてください。テクノロジーに興味はあるものの、詳細を知らない人にコンセプトを説明するつもりで記述します。

書式設定

ファイル形式

読みやすくするため、1 行の文字数は 80 文字以内にします。長いリンクやコードスニペットは長くてもかまいませんが、新しい行で始める必要があります。例:

リンク

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

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

プレースホルダ

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

コード

コードサンプルはデベロッパーの強い味方です。これらの記述方法はすでにご存じかもしれませんが、いくつかのヒントをご紹介します。

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

コードブロック

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

```shell
...

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

インラインのコード形式

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