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