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

Bazel のドキュメントにご協力いただき、ありがとうございます。これにより ドキュメント スタイルガイドを参照してください。スタイルに関する質問では 確認するには、 Google デベロッパー向けドキュメントのスタイルガイド

原則の定義

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

• 簡潔。できる限り少ない単語を使用します。
• クリア。わかりやすい言葉を使う。小学 5 年生向けの専門用語を使わずに書く あります。
• 整合性。概念の繰り返しには同じ単語やフレーズを使用する 確認しました。
• 正解です。次の期間中はコンテンツが正しくなくなるように書く 時間ベースの情報や将来への約束を避けることで可能になります。

文章作成

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

見出し

• ページレベルの見出しは H2 から始まります。（H1 見出しはページタイトルとして使用されます）。

• ヘッダーはできるだけ短くします。このようにして、 ラップなし。

  • ○: 権限
  • いいえ: 権限に関する簡単な説明

• 見出しでは文頭を大文字にする

  • はい: ワークスペースを設定します。
  • いいえ: ワークスペースを設定します

• 見出しはタスクベースまたは実用的なものにしてください。見出しが概念的な場合 理解がベースであることもありますが、ユーザーの行動を記載します。

  • ○: グラフの順序を保持する
  • いいえ: グラフの順序を保持します。

名前

• Bazel や Starlark などの固有名詞は大文字にします。

  • Yes: ビルドが終了すると、Bazel はリクエストされたターゲットを出力します。
  • いいえ: ビルドの最後に、bazel はリクエストされたターゲットを出力します。

• 一貫性を保つ。既存のコンセプトに新しい名前を付けないでください。説明 で定義される用語を 用語集。

  • たとえば、Compute Engine インスタンスに対するコマンドの発行について このページでターミナルとコマンドラインの両方を使用しないでください。

ページスコープ

• 各ページには 1 つの目的を持たせ、 始まります。これにより、読者は必要な情報をすばやく見つけることができます。

  • ○: このページでは、Windows に Bazel をインストールする方法について説明します。
  • いいえ: （導入の文章はありません。）

• ページの最後で、次に行うべきことを読者に伝えます。ページが 明確なアクションはありませんが、類似したコンセプトへのリンクを含めることができ、 サンプル、その他の探索の道筋を示します。

件名

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

• 読み手を「あなた」として呼びかけます。（なんらかの理由で「あなた」を使用できない場合は、 ジェンダー ニュートラルな表現を使用することなど）

  • ○: Bazel を使用して Java コードをビルドするには、 JDK をインストールする必要があります。
  • 可: Bazel で Java コードをビルドする場合は、JDK をインストールする必要があります。
  • いいえ: ユーザーが Java コードを JDK をインストールする必要があります。

• 対象読者が Bazel の一般ユーザーでない場合は、 セクション内に配置する必要があります。その他のオーディエンス 管理者、コントリビューター、移行担当者、その他の役割を担うことができます。

• 「私たち」を避けましょう。ユーザー ドキュメントには作成者がいません。人々に何を伝えるかを 考えています

  • はい: Bazel の進化に合わせて、コードベースを更新して、 サポートしています。
  • いいえ: Bazel は進化を続けており、 互換性がないため、Bazel ユーザーによる変更が必要です。

時間の経過

可能な限り、時期的な方向性を示す用語は使用しないでください。たとえば （2022 年第 2 四半期）、たとえば「今」、「現在」、「まもなく」という語句を入力します。これらの 将来の予測の場合は不正確になる可能性があります代わりに 代わりに「Bazel X.x 以降でサポート <feature>または GitHub の 問題リンクをご覧ください

• ○: Bazel 0.10.0 以降をサポートします。 リモートキャッシュできます
• いいえ: Bazel でまもなくリモート キャッシュへの保存は 2017 年 10 月に実施される予定で

Tense

• 現在形を使用する。どうしても必要な場合を除き、過去形や未来形は避ける をご覧ください。

  • Yes: Bazel はエラーを発します。 このルールに一致しない依存関係を検出します。
  • いいえ: Bazel で検出された依存関係が このルールに準拠していない場合、Bazel はエラーを発行します。

• 可能であれば、能動態（主語が物体に作用する声）を使い、 受動態（物体が主語となる態度）。一般的に 能動態では誰に責任があるのかがわかるため、文章が明確になります。条件 能動態を使うと明瞭さが損なわれ、受動態を使います

  • ○: Bazel は X を起動し、 表示されます。
  • いいえ: X が Bazel で開始され、その後 出力で Y がビルドされます。

トーン

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

• 口語的な言葉は避ける。次の単語は翻訳が難しくなります 英語に固有です。

  • はい: 適切なルールセット
  • いいえ: 適切なルールセットとは何でしょうか。

• 過度にフォーマルな言葉は避ける。問題を説明するように書いてください。 テクノロジーに興味はあるものの、詳細はわからない人に提供します。

書式設定

ファイル形式

読みやすくするために、行は 80 文字で折り返します。長いリンクまたはコード スニペット 長くすることもできますが、新しい行で始める必要があります。例:

リンク

• 「ここ」ではなく、わかりやすいリンクテキストを使用します「下」で表します。このプラクティス ドキュメントのスキャンがしやすく、スクリーン リーダーに適しています。

  • ○: 詳しくは、[Bazel のインストール] をご覧ください。
  • いいえ: 詳しくは [こちら] をご覧ください。

• 可能であれば、リンクで文を終了します。

  • ○: 詳しくは、[link] をご覧ください。
  • いいえ: 詳しくは [link] をご覧ください。

リスト

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

プレースホルダ

• ユーザーが変更する必要がある変数は山かっこで囲みます。 マークダウンで、山かっこをバックスラッシュでエスケープします（\<example\>）。

  • はい: bazel help <command>: 印刷 <command> のヘルプとオプション
  • いいえ: bazel help コマンド: ヘルプを出力 「command」コマンドと

• 特に複雑なコードサンプルの場合は、意味のあるプレースホルダを使用する 必要があります。

目次

サイトでサポートされている自動生成された TOC を使用してください。手動の TOC を追加しないでください。

コード

コードサンプルはデベロッパーにとってです。データ アナリストとして ここでヒントをご紹介します

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

コードブロック

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

```shell
...

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

インラインのコード形式

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