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] をご覧ください。
リスト
- 順序付きリストを使用して、ステップでタスクを達成する方法を記述する
- タスクベースではないことをリストするには、順序なしリストを使用します。（ アルファベット順、重要度など、特定の順序であること）
- 並列構造で記述します。例:
- すべてのリスト項目を文にします。
- 同じ時制の動詞から始めます。
- 従うべき手順がある場合は、順序付きリストを使用します。
プレースホルダ
ユーザーが変更する必要がある変数は山かっこで囲みます。 マークダウンで、山かっこをバックスラッシュでエスケープします（
\<example\>）。- はい:
bazel help <command>: 印刷<command>のヘルプとオプション - いいえ: bazel help コマンド: ヘルプを出力 「command」コマンドと
- はい:
特に複雑なコードサンプルの場合は、意味のあるプレースホルダを使用する 必要があります。
目次
サイトでサポートされている自動生成された TOC を使用してください。手動の TOC を追加しないでください。
コード
コードサンプルはデベロッパーにとってです。データ アナリストとして ここでヒントをご紹介します
小さなコード スニペットを参照する場合は、それを文に埋め込むことができます。 コマンドをコピーするなど、リーダーにコードを使用させたい場合は、コードを使用してください。 ブロックします。
コードブロック
- 広告は短くしましょう。冗長なテキストや不要なテキストをすべてコードから除外する 表示されます。
- Markdown で、サンプルの言語を追加してコードブロックのタイプを指定します。
```shell
...
- コマンドと出力を異なるコードブロックに分離します。
インラインのコード形式
- ファイル名、ディレクトリ、パス、小規模なコードにはコードスタイルを使用します。
- 斜体、「引用符」、太字で表示されます。
- はい:
bazel help <command>: 印刷<command>のヘルプとオプション - いいえ: bazel help コマンド: ヘルプを出力 「command」コマンドと
- はい: