技術ドキュメントを、プロジェクトの決まりどおりに、リンクを壊さず直す

## 直す前に、直してよいファイルと自動で作られたファイルを見分ける - 執筆された本文、再利用するインクルード、テンプレート、構造化データ、静的アセット、自動生成されるリファレンスがどこに置かれているか確認する。 - リポジトリのコントリビューターガイド、スタイルガイド、コンポーネントリファレンス、フロントマターの規則を正本として扱う。 - 変更する前に、編集可能なソースと、外部から取り込まれたコンテンツまたは自動生成されたコンテンツを区別する。 - 外部から取り込まれたファイルや自動生成されたリファレンスページを直接編集しない。上流の正本を特定し、そこで修正する。 - ローカル検証の失敗が保護対象のコンテンツに由来する場合は、ローカルの回避策を適用せず、責任を持つ上流の正本を報告する。 ## リンクは実際のファイルの場所で書き、行き先を確かめる - 公開システムがソースパスを書き換えるか、接頭辞を取り除くか、別名を設定するか確認する。 - ビルドシステムがソースツリーを基準にリンクを解決する場合、公開URLの方が短くても、内部参照には完全なソースパスを使う。 - 小文字化やslug化の規則を含め、実際のレンダラーが生成する見出しIDとアンカーが一致するか確認する。 - 代替リンクを推測せず検証する。移行方法が確立していて、アンカーを含まない安全なURLを使える場合を除き、移行先を確認できなければ変更をブロックする。 - 存在しないアセットの参照を変更する前に、表示されているソースフォルダだけでなく、フレームワークの仮想ファイルシステムと依存関係が提供するアセットも調べる。 ## プロジェクトで決まった言葉を使い、短くまっすぐな文で書く - 直接的かつ簡潔な能動表現で書く。 - 曖昧な表現、宣伝的な水増し、メタ的な注釈、作業を簡単だと見せる言い回しを取り除く。 - 読者を中心にした手順を優先し、所有関係を明示する必要がある場合は製品名またはシステム名を書く。 - リポジトリで承認された用語、大小文字、UI操作の動詞、強調規則を使う。 - 挙動が導入された時点を説明する恒久的なバージョン注記は残し、時間の経過で意味が変わる相対的な表現を避ける。 - 正当な技術用語は、適用範囲が最も狭い語彙許可リストに加える。正式な大小文字を使い、無関係な検査まで抑制する広すぎるパターンを避ける。 ## 各ページのタイトルと説明を入れ、埋め込み部品を正しく書く - ページタイトル、プレビュー用の説明、検索キーワードなど、必須のメタデータ項目をすべて含める。 - ナビゲーションラベルを文書化された制限内に収め、セクションで必要な場合だけ並び順の項目を使う。 - フレームワークのショートコードや埋め込みコンポーネントを書く前に、コンポーネントリファレンスを確認する。不正な構文は明確な失敗を示さないまま壊れた生成物を作ることがある。 - クライアント側UIディレクティブについて文書化された挙動に従う。一方が他方を恒久的に上書きする場合は、2つの非表示方式を併用せず、フレームワークの初期化前クローク方式を使う。 - ローカルビルドまたはワークツリーの制限を回避する目的だけで、グローバル設定を変更しない。 ## 直したファイルから先に整形とチェックをかけ、必要ならサイト全体も確かめる - 編集後、変更したファイルにリポジトリ指定のフォーマッターを実行する。 - より広い検証の前に、マークアップと文章をまとめて確認するファイル単位のリンターを実行する。 - 増分作業では対象を絞った検証を優先し、無関係な失敗に結果を埋もれさせない。 - 変更がルーティング、共有コンポーネント、ナビゲーション、自動生成されるリファレンス、その他のページ横断挙動に影響する場合は、サイト全体のビルドとリンク検査を行う。 - 一括検証ターゲットが環境と互換性を持たない場合は、サポート対象の検査を個別に実行し、設定は変更しない。 - 別の指示を待たずに該当する検証を完了し、実行できなかった検査があれば報告する。 ## 1つの問題に1つの小さな変更で直し、レビューの指摘には全部返事する - 1つの課題につき、焦点を絞った1つの変更セットを作る。周辺の整理や無関係なリファクタリングをドキュメント修正へ混ぜない。 - ファイルを明示的にステージする。ロックファイルや自動生成された変更まで取り込む広範囲のステージコマンドは絶対に使わない。 - コミット前にステージ済みファイルの一覧を確認し、意図したドキュメント範囲の外にあるものを対象から外す。 - push先がコントリビューターのフォークまたは承認済みのリモートであり、保護された上流リポジトリではないことを確認する。 - Issue報告やレビュー提案は、検証すべき主張として扱う。ドキュメントを変更する前に、実際の挙動を確認する。 - レビュー指摘へ対応した後は、別のレビューAPIが必要になる行単位のコメントを含め、すべてのレビュースレッドへ返信する。 - 便利なコマンドが信頼できない場合は、ラベルとメタデータを保持できると確認済みのサービスエンドポイントを使う。 ## ページを消す時や新しい版を足す時に、リンク切れを残さない - ページを削除する前に、執筆されたコンテンツとナビゲーション設定から、そのslug、タイトル、別名、参照元を検索する。 - バージョン付きリファレンスを更新する際は、中央のバージョン設定の更新、新しいバージョンページの作成、以前のページから最新版の別名を移す作業を1つの変更にまとめる。 - 2つのバージョンページに同じ最新版の別名を同時に持たせてはならない。 - 自動生成されるリファレンスでは、上流の仕様またはジェネレーターを変更して生成し直し、生成済みページを手作業で編集しない。 - 修正を最小限に保ち、実際の失敗を検証し、所有関係または外部の根拠が未解決なら明確なエスカレーション経路を残す。