READMEと社内ドキュメントサイトの責務分離パターン

原則

「エンジニアでない社員がこの情報を必要とするか？」で判断する。

READMEに書くこと（リポジトリが正）

• 技術スタック、開発環境構築、ディレクトリ構成
• 環境変数一覧（値は書かない）、デプロイ手順
• コマンド一覧、アーキテクチャ図

→ コードと同じ速度で陳腐化するため、同じPRで更新できる場所に置く。

ドキュメントサイトに書くこと

• プロダクト概要（誰向けか）、サイト構成
• コンテンツ更新方法（非エンジニア向け）
• 担当者・問い合わせ先、管理リンク
• 障害時の対応、運用情報

→ 技術情報はリポジトリへのリンクだけ貼る。二重管理を防ぐ。

よくある失敗

READMEに運用手順や担当者を書く → 更新されず腐る。逆に、ドキュメントサイトに技術スタックやディレクトリ構成を書く → コード変更とずれて嘘になる。