Bazel のドキュメントにご貢献いただきありがとうございます。これは、ドキュメントの作成を開始するための簡単なスタイルガイドとして使用できます。このガイドで解決できないスタイルに関する質問については、Google デベロッパー向けドキュメントのスタイルガイドに沿って対応してください。
原則の定義
Bazel のドキュメントは、次の原則を遵守する必要があります。
- 簡潔。できるだけ少ない単語を使用する。
- クリアします。平易な言葉を使う。5 年生の読解レベルに合わせて、専門用語を使わずに記述します。
- 一貫性がある。ドキュメント全体で繰り返し使用するコンセプトには、同じ単語やフレーズを使用します。
- 正解です。時間ベースの情報や将来の約束を避け、コンテンツが可能な限り長く正しい状態になるように記述します。
文章作成
このセクションでは、基本的な文章作成のヒントを紹介します。
見出し
- ページ単位の見出しは H2 から始まります。（H1 見出しはページのタイトルとして使用されます）。
ヘッダーは、できるだけ短くします。これにより、折り返しなしで TOC に収まります。
- はい: 権限
- いいえ: 権限に関する簡単な説明
見出しは文頭を大文字にします
- はい: ワークスペースをセットアップします。
- いいえ: ワークスペースを設定する
見出しはタスクベースまたは実行可能なものにします。見出しが概念的な場合は、理解に基づくものでも、ユーザーが行う操作を記述します。
- はい: グラフの順序を保持する
- いいえ: グラフの順序の保持について
名前
Bazel や Starlark などの固有名詞は大文字で記述します。
- はい: ビルドの最後に、Bazel はリクエストされたターゲットを出力します。
- いいえ: ビルドの終了時に、Bazel はリクエストされたターゲットを出力します。
一貫性を保ちましょう。既存のコンセプトに新しい名前を付けないでください。該当する場合は、用語集で定義されている用語を使用します。
- たとえば、ターミナルでコマンドを発行する方法について説明する場合は、ページでターミナルとコマンドラインを使用することは避けてください。
ページ スコープ
各ページには 1 つの目的があり、その目的は最初に定義する必要があります。これにより、読者は必要な情報をすばやく見つけることができます。
- はい: このページでは、Windows に Bazel をインストールする方法について説明します。
- なし:（導入文なし）
ページの最後に、次にどのような行動をとってほしいのか読者に伝えます。明確なアクションがないページには、類似のコンセプト、例、その他の探索方法へのリンクを含めることができます。
件名
Bazel のドキュメントでは、主な対象はユーザー（Bazel を使用してソフトウェアをビルドするユーザー）である必要があります。
読者を「あなた」と呼びます。（なんらかの理由で「あなた」を使用できない場合は、「彼ら」など、性別によらない表現を使用してください）。
- はい: Bazel を使用して Java コードをビルドするには、JDK をインストールする必要があります。
- MAYBE: ユーザーが Bazel で Java コードをビルドするには、JDK をインストールする必要があります。
- いいえ。Bazel で Java コードをビルドするには、JDK をインストールする必要があります。
対象が一般的な Bazel ユーザーでない場合は、ページの最初またはセクションで対象を定義します。その他のオーディエンスには、メンテナー、コントリビューター、移行担当者などのロールが含まれます。
「Google」という表現は避けてください。ユーザー向けドキュメントには作成者はありません。できることをユーザーに伝えるだけです。
- はい: Bazel が進化するにつれて、互換性を維持するためにコードベースを更新する必要があります。
- いいえ: Bazel は進化しており、Bazel に互換性のない変更が加えられ、Bazel ユーザーによる変更が必要になることがあります。
時間の経過
可能であれば、特定の日付（2022 年第 2 四半期）を参照したり、「今すぐ」、「現在」、「まもなく」などの時間に関する用語を使用したりしないでください。これらのデータはすぐに古くなり、将来の予測の場合は不正確になる可能性があります。代わりに、バージョン レベル（「Bazel X.x 以降は <feature> をサポート」など）または GitHub の問題のリンクを指定します。
- はい: Bazel 0.10.0 以降はリモート キャッシュをサポートしています。
- いいえ: Bazel はまもなくリモート キャッシュをサポートする予定です（2017 年 10 月頃）。
Tense
現在時制を使用します。明確にするために絶対に必要な場合を除き、過去形や未来形は使用しないでください。
- はい: このルールに準拠していない依存関係が見つかった場合、Bazel はエラーを出力します。
- いいえ: Bazel がこのルールに準拠していない依存関係を見つけると、Bazel はエラーを出力します。
可能であれば、受動態（主語が目的語に対して作用する）ではなく、能動態（主語が目的語に対して作用する）を使用します。一般的に、能動態は責任者を示しているため、文章が明確になります。能動態を使用するとわかりにくくなる場合は、受動態を使用します。
- はい: Bazel は X を開始し、出力を使用して Y をビルドします。
- いいえ: X は Bazel によって開始され、その後、出力を使用して Y がビルドされます。
トーン
ビジネスに適したトーンで記入してください。
口語的な表現は避けてください。英語に固有のフレーズを翻訳するのは難しい。
- はい: 優れたルールセット
- いいえ: では、適切なルールセットとはどのようなものですか？
過度に堅苦しい表現は避けてください。テクノロジーに興味はあるものの、詳細を知らない人にコンセプトを説明するつもりで記述します。
書式設定
ファイル形式
読みやすくするために、1 行の文字数は 80 文字以内にします。長いリンクやコード スニペットは長くてもかまいませんが、新しい行で始める必要があります。次に例を示します。
リンク
「こちら」や「下記」などのあいまいなリンクテキストではなく、説明的なリンクテキストを使用してください。これにより、ドキュメントのスキャンが容易になり、スクリーン リーダーに適しています。
- はい: 詳細については、[Bazel のインストール] をご覧ください。
- いいえ: 詳しくは、[こちら] をご覧ください。
可能であれば、文の最後にリンクを追加します。
- はい: 詳しくは、[リンク] をご覧ください。
- いいえ: 詳しくは [リンク] をご覧ください。
リスト
- 順序付きリストを使用して、手順でタスクを完了する方法を説明する
- タスクベースではない項目をリストする場合は、番号なしリストを使用します。（アルファベット順、重要度など、並べ替え順序は必要です）。
- 並列構造で記述します。例:
- すべてのリスト項目を文にします。
- 同じ時制の動詞から始めます。
- 手順がある場合は、順序付きリストを使用します。
プレースホルダ
ユーザーが変更する必要がある変数には、角かっこを使用します。Markdown では、バックスラッシュ（
\<example\>）を使用して角かっこをエスケープします。- はい:
bazel help <command>:<command>のヘルプとオプションを出力します。 - いいえ: bazel help コマンド: 「コマンド」のヘルプとオプションを出力します。
- はい:
特に複雑なコードサンプルの場合は、コンテキストで意味のあるプレースホルダを使用します。
目次
サイトがサポートしている自動生成された TOC を使用します。手動で TOC を追加しないでください。
コード
コードサンプルはデベロッパーの強い味方です。これらの記述方法はすでにご存じかもしれませんが、いくつかのヒントをご紹介します。
小さなコード スニペットを参照する場合は、そのスニペットを文に埋め込むことができます。読者にコードを使用させる場合は、コマンドのコピーなど、コードブロックを使用します。
コードブロック
- 広告は短くしましょう。コードサンプルから冗長なテキストや不要なテキストをすべて削除します。
- Markdown では、サンプルの言語を追加してコードブロックのタイプを指定します。
```shell
...
- コマンドと出力を別のコードブロックに分離します。
インライン コードの書式設定
- ファイル名、ディレクトリ、パス、短いコードにはコードスタイルを使用します。
- 斜体、引用符、太字ではなく、インライン コードのスタイルを使用します。
- はい:
bazel help <command>:<command>のヘルプとオプションを出力します。 - いいえ: bazel help コマンド: 「コマンド」のヘルプとオプションを出力します。
- はい: