write-docs

ドキュメントを書く

ドキュメントは用語集です。構成要素に名前を付け、それぞれが存在する理由を説明し、コードを検索しても読み取れない原則を伝えます。現時点で何が存在するかについてはコードが信頼できる唯一の情報源です。ドキュメントは決してコードに遅れてはいけません。何かを書く前に、このスキルを左右する次の問いを必ず考えてください。読者はコードを読んだほうが、より速く、より確実に情報を得られるでしょうか？ そうであれば、内容を転載せず、コードを参照するよう案内してください。

残すものと削るもの

残すもの — 読者がコード検索だけではたどり着けない情報です。

• WHY：あるものが存在する理由、分割の背後にある原則、分類。ファイル名からは分からないこと。
• 自明ではない発見：プラットフォーム固有の癖、「これを削除すると、Y が原因で X が壊れる」、2 つのファイルが暗黙に共有する契約。
• ものの所在を示す参照と、そこにあるものの種類、および何を置くべきかのルール。

削るもの — すでにコードや Git の履歴にあるため、コピーしても古くなるだけの情報です。

• 正確な一覧：シーン名、シナリオ表、ヘルパーの一覧、クラス ID、ファイル一覧、コマンド／フラグの対応表。
• 物語や変更履歴：「X の名前を変更した」、「古い Y は重複していたため削除した」、試したことや断念したこと。
• 正確な件数、tick 値、現在の定数、行番号など、コードをそのまま言い換えただけの情報。

転記せず、参照先を示す

具体的な項目を列挙したくなったら、それらを管理するフォルダーや単一のファイルを示し、読者をそこへ案内してください。ファイルよりフォルダーを優先し、転記したコピーより信頼できる唯一の情報源となるレジストリを優先してください。 ヘルパーモジュールについて説明する場合は、そこに含まれるヘルパーの種類と、何を含めるべきかのルールを説明し、現在の一覧は載せません。原則を具体的に示す例は 1 つで十分です。全項目の一覧は避けるべき兆候です。「マッチアップは定義されている表にあり、ID はクラスレジストリを参照する」は次の編集後も正しいままですが、どちらかをそのまま再掲すれば、いずれ古くなります。

事実ごとに置き場所を 1 つにする

各事実には正式な置き場所を 1 つだけ設け、それ以外のドキュメントからはそこへリンクします。ドキュメント間の重複は保守上の不具合です。コピーは食い違い、どれが最新か読者には分からなくなります。ルート／全体ドキュメントには短いセクションと、下位ドキュメントへの参照を置きます。2 つのドキュメントが同じ内容を説明している場合は、ハブを選び、もう一方は参照だけにします。

ツリーを下向きにリンクする

ドキュメントは、1 つのルート／ハブドキュメントからたどれるツリーを形成します。ハブは各下位ドキュメントにリンクし、下位ドキュメントはその下にあるモジュールレベルのドキュメントへリンクします。ナビゲーションは下向きです。読者はルートから始めてリンクをたどるため、ツリー全体をそこからたどれます。ドキュメントから親や兄弟へリンクするのは、そこにすでにある事実を再利用する場合に限ります。たとえば、アプリのドキュメントからハブのデプロイセクションを参照して重複を避ける場合や、ある境界のドキュメントから詳細を委ねる兄弟ドキュメントを示す場合です。これこそ、一置き場のルールが機能している状態です。追加しないのは、情報を何も伝えない定型的な「X の一部です」という逆向きリンクです。これはノイズであり、ルートからツリーをたどれるため、そもそも必要ありません。

編集の手順

既存のドキュメントを整理するときは、コードから分かる項目の列挙、変更履歴や物語、コードを言い換えただけの文を見つけ次第削除します。次に、会話の経緯を知らない第三者のつもりで、残った内容を読み直してください。残す各行は、原則、理由、または参照先のいずれかであるべきです。その行がリンクと同じくらい正確で役立つなら、リンクに置き換えてください。