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