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