reStructuredTextで、例付きの技術文書を書いてビルドで確かめる

## 読む人に必要な事を説明し、細かい中身はコードに任せる ドキュメントで扱う動作を理解し、利用する必要がある読者に向けて書く。概念はできるだけ明確かつ簡潔に説明する。読者の判断に役立つ場合は低レベルの詳細も含めるが、非常に深い実装内部の説明はソースコードに委ねる。 - メソッドを正しく使ううえでシグネチャが重要な場合に限り、そのシグネチャを説明する。 - 利用可能なすべてのスイッチではなく、主要なワークフローに影響するコマンド引数とオプションを記載する。 - コード内のメッセージだけで原因と対処法が明らかなエラーや例外を、ドキュメントで繰り返し説明しない。 - 網羅的な一覧よりも、焦点を絞った説明、現実的な例、関連する詳細へのリンクを優先する。 ## 変更の種類とリリース情報から、入れる先のブランチを選ぶ メンテナンス対象バージョンの一覧を決め打ちしない。対象ブランチを選ぶ前に、プロジェクトの正本となるリリースメタデータを読み、変更種別ごとの規則を一貫して適用する。 - バグ修正は、そのバグが存在する最古のメンテナンス対象ブランチへ反映する。 - 新機能のドキュメントは、その機能が導入されたブランチへ反映する。そのブランチがすでにメンテナンス対象外なら、次に該当するメンテナンス対象ブランチを使う。 - 誤字、言い換え、再構成、その他の非機能変更は、最古のメンテナンス対象ブランチへ反映する。 - 独立してバージョン管理されるサブプロジェクトのドキュメントには、そのプロジェクトが定めた方針を適用する。指定がある場合は、新機能を含むすべての変更を最古のメンテナンス対象ブランチへ反映する。 変更種別と、判断に使ったメンテナンス情報を記録する。リリースメタデータを取得できない、または解釈が曖昧な場合は、ブランチを推測しない。 ## 見出しの記号と折り返しの長さをそろえる 見出しレベルの下線文字を一貫して使う。レベル1には等号、レベル2にはハイフン、レベル3にはチルダ、レベル4にはピリオド、レベル5には二重引用符を使う。各下線は見出しテキストの全長に合わせる。リポジトリがパス固有の見出し例外を定めている場合は、その例外を適用する。 本文は80文字で折り返す。ただし、表、URL、孤立行など、折り返すと読みやすさが下がる場合は例外とする。リストの箇条書き記号は行頭に置く。太字や斜体の範囲を複数行にまたがらせない。 インラインコードには、対になった二重バッククォートを使う。既定言語のコード例には簡潔な二重コロン形式を使うが、マーカーだけが単独行になる場合は使わない。言語やレンダリング文脈を明示する必要がある場合は、明示的な code-block ディレクティブを使う。 ## 命令（ディレクティブ）の字下げとリンクの書き方をそろえる ディレクティブの内容は4スペースでインデントする。二重コロンのマーカーの後は、内容の前に空行を置く。また、各ディレクティブの前後にも空行を置く。複数行にわたるリスト項目の継続行は、その項目のテキスト開始位置に揃える。 メッセージに合う標準の admonition、つまり note、tip、warning、caution、seealso のいずれかを使う。バージョン追加と非推奨化には、それぞれ専用のディレクティブを使い、対象バージョンと短い説明を添える。 内部ドキュメントへのリンクには絶対ドキュメントパスを使う。特定の節へリンクする場合は、ラベル付きの相互参照を使う。相対的な内部パスは使用しない。 外部サイトへのリンクは、URLを本文へ埋め込まず、名前付きリンクターゲットをファイル末尾に置く。言語APIのクラス、メソッド、関数、組み込み型には、ドキュメントシステムが用意する専用ロールを使う。 ## YAMLやXMLなどの設定例を、いつも同じ順番で並べる 機能が複数の設定形式に対応する場合は、configuration-block ディレクティブですべての対応形式を示す。読者がページごとに配置を覚え直さず比較できるよう、リポジトリ全体で順序を統一する。 - サービスと一般設定では、YAML、XML、プログラミング言語形式の順にする。 - ルーティング、検証、オブジェクトマッピングでは、属性、YAML、XML、プログラミング言語形式の順にする。 - 翻訳リソースでは、XML、YAML、プログラミング言語形式の順にする。 通常のタブは、代替ツールやワークフローなど、設定以外の並列コンテンツにだけ使う。フレームワーク統合アプリケーションとスタンドアロンアプリケーションで例が異なる場合は、レンダラーと読者が文脈を区別できるよう、別々の言語識別子を使う。 ## 本物らしい名前と、ファイル名のコメントでコード例を書く 対象言語のコーディング規約と、プロジェクトで確立されたベストプラクティスに従う。意図が分かりにくくなる仮の単語ではなく、現実的な名前と場面を使う。予約済みの例示用ドメインと、リポジトリで定めたサンプルベンダー名を使う。 - 可能な限り、コードブロックの行は85文字で折り返す。 - YAMLを含め、例は4スペースでインデントする。 - 例の実行や型の理解に役立つ場合は、名前空間と import 宣言を含める。 - コードブロックの先頭にはファイル名を示すコメントを置く。次の行もコメントでない限り、間に空行を入れない。 - すべてのシェルコマンドの先頭にプロンプトマーカーを付ける。 - 省略したブロックを畳む場合は、その言語に合ったコメント形式を使う。 - 同じ行にある値の一部を短縮する場合は、コメント記号を付けず省略記号だけを使う。 - 必要な場合は、YAMLのインラインマッピング内の空白など、形式固有の空白規則を守る。 例は、実運用ですべてを網羅しているように見せかけず、対応している手順を教えるものにする。提示したコードが失敗する原因となる前提条件を省かない。 ## やさしいアメリカ英語で書き、「simply」などの言葉を避ける アメリカ英語で書く。節見出しにはタイトルケースを使う。最初と最後の単語、および主要語を大文字で始め、短い機能語は見出しの先頭でない限り小文字にする。 書き手には「we」を使わず、読者には「you」を使う。性別を限定しない代名詞を使う。世界中の読者が理解できるよう、能動態、基本的な語彙、直接的な文を優先する。短縮形は使用してよい。 オックスフォードコンマは使わない。「obviously」「simply」「just」「easy」「clearly」「trivial」「of course」のような慣用的または読者を見下す語を避ける。こうした語は説明不足を隠し、読者を萎縮させることがある。 すべての画像に簡潔な代替テキストを付ける。先頭を大文字にし、末尾をピリオドにする。「A screenshot of」や「Diagram of」で始めない。複雑な図は、すべての詳細を代替テキストへ詰め込まず、周囲の本文で説明する。 ## 終える前に文書をビルドし、警告や壊れたリンクを確かめる ディレクトリ名には末尾のスラッシュを付け、ファイル拡張子には先頭のピリオドを付ける。ディレクトリツリーの例では、`your-project/`のような中立的なサンプルプロジェクトルートを使う。本文と例の間で、ファイル名、パス、コマンド、参照ターゲットを一致させる。 ドキュメント変更を完了とみなす前に、次を行う。 1. 指定されたビルド用ワークスペースへ、ドキュメントのビルド依存関係をインストールする。 2. リポジトリで定められたビルドコマンドを実行する。 3. 目視確認が必要な場合は、生成物を一時配信する。 4. 変更したページについて、警告、壊れた参照、不正なディレクティブ、コードの表示、見出し階層、画像説明を確認する。 5. 選択した対象ブランチが、変更種別と現在のメンテナンス情報に引き続き合っていることを確認する。 リポジトリにドキュメントビルド手段がある場合は、ソースの目視確認だけで成功と報告しない。