データから作る多言語のリンク集を、ページを手で直さずに管理する

## リンク集のページは、データから作られる物だと知っておく あなたが維持するのは、人が読む出力が「生成される」ものであり「著述される」ものではない、厳選ナレッジベースである。何かに手を付ける前に、この分離を理解しておくこと。 - **正となるデータ**は、構造化されたデータファイル一式である。カテゴリー／セクションのツリー（アンカーと目次を定義する）と、セクションごとの1つのエントリーファイルからなる。 - **生成される成果物**——人が読むリスティングドキュメント（対応言語ごとに1つ）や、機械可読のインデックス——は、このデータからジェネレータースクリプトによって生成される。これらは使い捨てであり、必要に応じて再構築される。 - 同じ基盤データは、自動化エージェント向けのランタイムクエリインターフェースにも供給されることがある。したがって、データ品質の影響は、レンダリングされたドキュメントの利用者だけにとどまらない。 ここには通常、アプリケーションのランタイムもビルドもテストスイートも存在しない。あらゆる変更は、構造化データ・ツールスクリプト・ドキュメントのいずれか3つのうちの1つである。このメンタルモデルを保つこと——それが、上書きされてしまう出力を編集してしまうという、最も多く最も被害の大きいミスを防ぐ。 ## ページを直さず、データを直してから作り直す - **生成された出力ドキュメントを直接編集してはならない。** 編集内容は次回の再生成で消え去る。読者に見える内容を変えたいなら、基盤データを変更すること。 - 項目を追加・変更するには、該当セクションのエントリーファイルを編集する。 - 新しいセクションを追加するには、まずカテゴリー／セクションツリーのファイルを編集し、その後に対応するエントリーファイルを作成する。作業後は、アンカー検証ツールを実行し、外部から参照されているアンカーが失われていないことを確認する。 - データを変更した後は、コミット前に必ずジェネレーターをローカルで実行し、生成されるすべてのファイルを最新化する。継続的インテグレーションは、新たに生成した出力と乖離したワーキングツリーを拒否する——だから、推測せずに再生成すること。 - 機械可読のインデックスを手作業で編集してはならない。これはジェネレーターによって完全に再生成される。 ## 項目の欄を埋め、外の読者向けに1文の説明を書く 各エントリーは、必須フィールド（安定した一意のID、URL、タイトル、カテゴリー、タイプ、難易度、対応言語セット、追加日、ステータス）を持つ構造化レコードであり、自動化によって埋められるオプションフィールド（アーカイブURL、最終確認タイムスタンプ、コンテンツフィンガープリント）を持つ。タイプ・難易度・言語・ステータスについては、定められた統制語彙を尊重し、値を勝手に作り出さないこと。 エントリーに付随する自由記述の説明文は、**外部公開用・第三者が読むことを前提としたコピー**として扱うこと。 - **含めるもの：** そのリソースが何であるかを説明する事実に基づく一文。任意で著者のバイラインを続けてよい。 - **除外するもの：** 内部的な事柄すべて——本プロジェクトへの言及、課題番号や変更リクエスト番号、「元々は〜が提案した」といった文言、その他あらゆる履歴的メタデータ。帰属情報はバージョン管理の履歴にすでに保存されている。外部の読者が、このエントリーと本リポジトリとの関係を推測できてはならない。 - 機械的に移行された値は、元の内容が誤っているか古くなっていない限り、手を加えずそのままにしておく。 - エントリーを外部アーカイブの対象から外すのは、原著者が明示的にそれを求めた場合（有料コンテンツ、削除要請）に限る。 ## 外からのリンクが切れないよう、見出しのリンク名を変えない 外部サイトと内部の目次は、いずれも名前付きアンカーを指している。既存のアンカーの名称変更や削除は、そのアンカーを指すすべての受信リンクを黙って壊してしまう。 - **既存のアンカーの名称を変更したり削除したりしてはならない。** 新しいセクションには新しいアンカーを追加すること。 - 継続的インテグレーションのガードが、現在のアンカーセットをベースラインと比較し、ベースラインのアンカーが1つでも欠けていればビルドを失敗させる。このガードは提案ではなく、絶対的な関門として扱うこと。 - ジェネレーターはエントリーを決定論的に（追加日、次いでタイトルの順で）ソートするため、エントリーを手作業で一括並べ替えしてはならない。エントリーをリストの前方に移動させたい場合は、レコードを並べ替えるのではなく、その追加日の値を変更すること。 ## 説明やコードは1つの言語で書き、項目ごとに載せる言語版を決める プロジェクトが著述するコンテンツは、単一の主要言語で書かれる。複数の言語が現れるのは、多言語性が成果物に本質的に組み込まれている箇所のみである。翻訳された出力ドキュメント、ローカライズされたセクションタイトルのオーバーライド、リソース本来の言語を保持するエントリーごとのタイトル、主要言語以外のプロンプトで発火させるためのトリガーフレーズなどである。それ以外——コード、コメント、フィールド名、テンプレート、パイプラインの出力、ラベル、コミットメッセージ——はすべて主要言語のままとする。 1つのエントリーは、その言語セットによって制御され、複数の言語版に存在してよい。 - 言語のヒントがない新規エントリー → 主要言語のみで掲載し、他の言語版にも掲載したいか投稿者に確認する。 - ある特定の地域に固有のリソース → その地域のロケールのみをタグ付けする。 - 真に文化横断的で規範となるリソース → 関連する言語すべてにタグ付けするか、ワイルドカードを控えめに使う。 - 構造を一致させるためだけに、あるエントリーを強制的に翻訳したり、他の言語版に強制的にミラーしたりしてはならない。各言語版は、他の言語版には存在しないエントリーを含んでいてよい。 ## 投稿を取り込む時に、投稿した人の名前の表示を残す 受信する依頼は2つの形式で届き、どちらも功績が失われないように取り込む必要がある。 - **構造化された提案（ブランチなし）：** エントリーをデータモデルへ直接取り込み、再生成し、検証ツールを実行したうえで、投稿者に功績を与える共著者トレーラーを付けてコミットする——このトレーラーが彼らへの唯一の功績表示となる。 - **直接の変更リクエスト（投稿者が自分のブランチでファイルを編集した場合）：** その作業は*投稿者自身のブランチ上で*取り込み、完全な帰属表示を保ったままマージされるようにする。直接の投稿者による変更を、自動化されたコーディングアシスタント経由で処理し、そのアシスタントが独自の競合するリクエストを開いて投稿者のものを閉じてしまうようなことは、決してしてはならない——それは投稿者のマージ功績を破壊する行為である。 自動化されたコーディングアシスタントは、**構造化された提案に限り、非同期のフォールバックとして**機能してよい。それはメンテナーが対応できず、かつキューを滞らせないために動かし続ける必要がある場合に限る。これはデフォルトの経路ではない。マージ前には人間が必ず結果をレビューする。アシスタントが節約するのはタイピングの手間であり、判断ではない。 ## 変更ごとに自動で確かめ、レビューのボットには助言だけさせる データまたはジェネレータースクリプトに触れる変更のたびに、パイプラインは次を行うべきである。 1. スキーマ検証とアンカー検証を実行する。 2. ジェネレーターを再実行し、ワーキングツリーが新たに生成した出力と乖離していれば警告する（投稿者が再生成を忘れたサインである）。 3. 自動レビューボットを呼び出し、公開済みのルーブリックに照らして新規エントリーをそれぞれ採点し、構造化されたコメントを1件投稿し、参考ラベルを付与する。 レビューボットは保守的に設計すること。投稿者の言語は（モデルを介さず）決定論的に検出し、それをディレクティブとして渡す。モデル呼び出しが失敗した場合は、区別可能な「レビュー失敗」ラベルのもとで、決定論的な到達可能性チェックとフォーマットチェックにフォールバックする。**このボットは自動マージも自動却下も一切行わない**——助言するだけであり、決めるのは人間である。 ## ページを手で直さず、決まりに無い変更は止まって人に聞く 以下は行わないこと。 - 生成された出力ドキュメントや機械可読のインデックスを手作業で編集する。 - 既存のアンカーの名称を変更したり削除したりする。 - テンプレート内で、プロジェクトが許可するタグのホワイトリストを超えたマークアップを導入する。 - ソートキーを調整する代わりに、既存のエントリーを一括で並べ替える。 - 明示的に依頼されない限り、貢献ガイドライン・行動規範・ワークフロー定義を編集する。 - 明示的に依頼されない限り、コミットを作成したりプッシュしたりする。 新しい言語版・新しいスキーマフィールド・新しいセクション分類法など、これらのルールが対象としない領域に変更が及ぶ場合は、独自に判断せず立ち止まって確認すること。貢献ガイドと採点ルーブリックの趣旨に沿い、迷ったときは行動する前に人間に確認すること。