コマンドの使い方を、よく使う例で見せる短い説明ページを書く

## 同じページが無いか探し、使えるOSごとの置き場所を決める 何かを作成する前に、すべての原文ページツリーと翻訳ページツリーから対象コマンドを検索する。既存ページがあれば重複を作らず、そのページを編集する。存在しなければ、記載する構文が実際に動作する場所を特定する。 - 同じ構文が少なくとも2つのプラットフォームで動作する場合に限り、コマンドを共通ディレクトリに置く。 - 1つのプラットフォームで動作するコマンドは、そのプラットフォームのディレクトリに置く。 - 英語ページは主要ページツリーに置き、翻訳は同じプラットフォームパスを持つロケール別ツリーに置く。 - プラットフォーム固有の方針でページタイトルまたは呼び出し時にコマンドの正式な大文字・小文字表記が必要な場合を除き、ファイル名には小文字を使う。 コマンドの評判や名前だけでディレクトリを選ばない。最初に対応プラットフォームと構文を検証する。 ## ページを短く保ち、タイトルと説明を例より前に置く 各ページを、次の固定順序を持つ小さなMarkdownリファレンスとして記述する。 1. リポジトリで大文字・小文字を区別しないことが認められている場合、その差を除いてコマンド名がファイル名と一致するH1を1つ置く。 2. 引用形式の説明を、できれば1行か2行で置く。 3. 山括弧で囲んだ上流URLを含む必須の「詳細情報」行を置く。 4. 実用例を置く。各例では命令形の箇条書き説明に続けて、インラインコード形式のコマンド行を別行に置く。 5. ファイル末尾に改行を置く。 例は5個を標準とし、8個を超えてはならない。説明とコマンドの間、および各例の間には空行を置く。ページ本文では太字、斜体、装飾目的のMarkdownを使わない。 ## よくある作業に役立つ例を選ぶ 最も一般的な実務上の作業を解決する例を選ぶ。説明は「ファイルを一覧表示する」のような命令形で書き、「ファイルを一覧表示します」のような叙述形にはしない。説明は短く行動中心にし、一般的なオペレーティングシステムの概念を解説しない。 すべての例を、そのコマンドのマニュアル、組み込みヘルプ、または公式文書と照合する。オプションと引数の間隔は文書どおりに保ち、コマンドが別の形式を明示的に要求しない限り、`--option arg`を使う。 該当する呼び出し方が存在する場合は、「ヘルプを表示する」と「バージョンを表示する」をこの順で最後の2例に置く。これらは優先度の低い例なので、より実用的な例が必要でページ上限を超える場合は、どちらか一方を省く。 ## 人が入れかえる部分を、二重の中かっこで示す 置き換え可能な値を二重中括弧で囲む。意味に応じて次のプレースホルダー形式を一貫して使う。 - ファイルシステム入力には`{{path/to/file}}`、`{{path/to/directory}}`、`{{filename}}`を使う。 - 複数の引数には`{{file1 file2 ...}}`を使う。 - 選択肢には`{{option1|option2}}`を使う。 - 数値範囲には`{{1..5}}`、ワイルドカードパターンには`{{*.ext}}`を使う。 - 同等の短いオプションと長いオプションには`{{[-v|--verbose]}}`を使う。 - ひとまとまりのフラグには`{{[-it|--interactive --tty]}}`を使う。 短い形式と長い形式の両方が存在する場合は、両方を示す。短い形式を作り出してはならない。バージョン指定フラグやその他の一般的なオプションは、コマンドごとに異なる。プレースホルダーを入れ子にしたり、必須の二重中括弧を単一の中括弧や角括弧に置き換えたりしない。 キー操作には山括弧を使い、`<a>`、`<Enter>`、`<Space>`、`<Ctrl>`、`<Alt>`、`<Shift>`と記述する。組み合わせは`<Ctrl c>`のように空白で区切り、連続操作は`<Esc><u>`のようにグループを隣接させる。 ## リンクが開けると確かめてから、公式マニュアルへつなぐ すべてのページに詳細情報へのリンクを置く。コマンドの公式マニュアル、プロジェクト文書、保守されているマニュアルページサービス、またはプラットフォーム提供元の文書を優先する。 リンクを採用する前にリダイレクトをたどり、最終レスポンスが成功していることを確認する。もっともらしく見えるだけのURLに依存しない。山括弧付きリンクは専用の「詳細情報」行に置き、一次情報が存在する場合は宣伝目的または非公式の情報源を避ける。 同じ信頼できる情報源を使って、コマンド名、オプション形式、引数の間隔、プラットフォーム上の動作、ヘルプ構文、バージョン構文を確認する。 ## ファイルの場所や変数の書き方を、WindowsなどOSごとに合わせる Windowsのコマンドページでは、リポジトリ方針で別の指定がない限りファイル名を小文字にする一方、H1と例ではコマンドの正式な大文字・小文字表記を保つ。パスのプレースホルダーにはバックスラッシュを使う。 環境変数は、記載対象のシェルに合った構文で書く。従来のコマンドインタープリターでは`%VARIABLE%`、PowerShellでは`$Env:VARIABLE`を使う。PowerShell向けの例は、ページでより狭い要件を明示しない限り、サポート対象の最古のエディションと現行エディションの両方で動作しなければならない。 その他のプラットフォームでは、各環境固有のパス、シェル、環境変数、オプションの規則に従う。共有ページが有効なのは、掲載したコマンド構文が実際に移植可能な場合に限る。 ## コマンドの別名と、サブコマンドごとのページを作る リポジトリにエイリアス用ヘルパーがある場合は、それを使ってエイリアスページを作成する。そのコマンドがエイリアスであることを明記し、上流情報へリンクし、元のコマンドのリファレンスページを開く例を1つ示す。翻訳されたエイリアスページも同じヘルパーで同期し、生成された構造を個別に編集しない。 サブコマンドを持つコマンドでは、個別ページがある代表的なサブコマンドを親ページの説明に記載する。文書化する各サブコマンドにはハイフン区切りの専用ページを用意し、該当するサブコマンドのリファレンスを開く例を含める。 専用ページに置くべき詳しいサブコマンドの作業手順を、親ページへ詰め込みすぎない。 ## コマンドやページの形を変えずに翻訳する 英語ページが存在してから翻訳する。例の構造、プラットフォームパス、コマンド、プレースホルダーを同じ状態に保つ。例示用に予約されたドメインは変更せず、リポジトリ方針で求められる場合はプレースホルダー内の単語を原文の言語のまま保つ。 英語の文法を機械的に写すのではなく、ロケール固有の記述規則を適用する。例： - 中国語では、ラテン文字および数字と中国語の間に空白を置き、全角の句読点を使う。 - フランス語では、例の説明を三人称で書き、必要な句読点の前に空白を置く。 - スペイン語では、三人称の説明と、推奨されるローカライズ済み技術用語を使う。 - ブラジルポルトガル語と欧州ポルトガル語では、三人称の説明を使う。 - インドネシア語では、不要な動詞接頭辞を付けず、簡潔なコマンド説明形式を使う。 英語正本と同じ構造チェックで翻訳ページを検証する。 ## 人が見る前に、チェック用ツールでページを確かめる 人によるレビューを依頼する前に、変更したファイルに対してリポジトリのページlinterを実行する。変更内容またはリポジトリ方針で必要な場合に限り、ツリー全体のlintを使う。 ページを次の観点でレビューする。 - タイトルとファイル名が一致している。 - 引用形式の説明が短く、有効な情報リンクがある。 - 推奨される例が5個あり、8個を超えていない。 - 説明が命令形で、空行が正しい。 - オプション形式が検証済みで、二重中括弧のプレースホルダーが使われている。 - プラットフォームディレクトリが正しく、各環境固有の構文になっている。 - ヘルプとバージョンの例を含む場合、それらが最後の位置にある。 - 装飾目的の書式がない。 - 翻訳がロケール固有の規則に従っている。 - ファイル末尾に改行がある。 機械的なタイトル、リンク、エイリアス、相互参照、コマンドの更新には、利用できる場合はリポジトリの保守スクリプトを使う。広範なスクリプト変更を行う前に、dry-runモードを優先する。 ## 書く前に、AIへマニュアルと似たページを渡す 作成前に根拠を渡して、AIコストと修正サイクルを減らす。エージェントに規則を思い出させるのではなく、コマンドのヘルプまたはマニュアルの出力、承認済みの類似ページ2個か3個、ページテンプレートを提供する。 最初に既存ページを確認する。関連するページの依頼は、文脈を共有できる場合にまとめる一方、各ページは個別にレビューする。8例の上限を埋めることを目的とせず、価値の高い例を5個か6個作成する。 人によるレビューの前にlinterを実行し、書式エラーによってレビュー担当者の注意を消費しないようにする。コスト削減は、入力の改善、再利用、決定論的な検証によって実現し、情報源の検証省略やページ品質の低下によって実現してはならない。