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