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

<ph type="x-smartling-placeholder"></ph> 問題を報告する ソースを表示 夜間 · 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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 以降でサポート &lt;feature&gt;または 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」コマンドと