1. 導入：ドキュメントの「情報の腐敗」を防ぐために
開発現場でよくある悩みの一つが「ドキュメントの所在が不明確」という問題です。コードの修正は完璧なのに設計書が古いまま、あるいはWikiの場所が分からず情報が散逸する……。こうした課題を解決するためには、ドキュメントの性質に合わせて「どこに置くべきか」というルールを明確にすることが重要です。本記事では、GitHub Wikiとリポジトリ内Markdown（Docs as Code）の最適な使い分けについて解説します。
2. 基礎知識：Docs as Code とは
Docs as Code とは、コードを管理するのと同様に、ドキュメントもGitで管理し、コードの変更と同期してレビューや更新を行う考え方です。
一方、GitHub Wiki は、リポジトリとは独立したGitリポジトリとして提供されており、誰でもブラウザ上で簡単に編集・保存が可能です。
・リポジトリ内Markdown：コードの変更と同時に更新できるため、設計のズレが発生しにくい。
・GitHub Wiki：編集のハードルが低く、プロジェクト横断的な情報や、仕様に関係ないナレッジの蓄積に向いている。
3. 実装・解決策：判断のフローチャート
以下の基準で置き場所を決めると、管理が劇的に楽になります。
・コードと密接な関係があるか？
→ Yes：リポジトリ内（docsディレクトリなど）に格納し、Pull Requestでコードと一緒にレビューする。
・エンジニア以外も頻繁に更新するか？
→ Yes：Wikiを採用し、編集権限を広く解放する。
・バージョン管理が必要か？
→ Yes：リポジトリ内（タグ付けでバージョンとドキュメントを紐付けられる）。
4. サンプルプログラム：リポジトリ内管理のディレクトリ構成例
以下は、Docs as Codeを実践するための一般的な推奨構成です。プロジェクト直下の `docs/` に集約し、READMEから参照させるのが定石です。
.
├── src/ # ソースコード
├── docs/ # ドキュメント管理ディレクトリ
│ ├── architecture.md # 設計方針（コード変更時に同期）
│ └── api-spec.md # API仕様書
├── README.md # プロジェクトの入り口
└── CONTRIBUTING.md # 開発への参加方法（Wikiではなくここに書くとエンジニアに伝わりやすい）
プロジェクト概要
詳細な設計情報については、[設計ドキュメント](./docs/architecture.md) を参照してください。
5. 応用・注意点：現場で陥りやすい罠
注意点1：情報の二重管理を避ける
「同じ内容をWikiとMarkdownの両方に書く」のは厳禁です。必ず「正（ソース・オブ・トゥルース）」をどちらにするか決めましょう。基本的には、コードと運命を共にする情報はリポジトリ内（Markdown）が正解です。
注意点2：Wikiの検索性と構造化
Wikiは便利ですが、階層構造が深くなると迷子になりがちです。Wikiを使う場合は、サイドバーを適切に編集し、トップページにインデックスを貼る運用を徹底してください。
まとめ
「コードと同期すべき情報はリポジトリへ、それ以外はWikiへ」。この原則を守るだけで、チームのドキュメント運用は驚くほど健全化します。まずはプロジェクトの設計書をリポジトリ内に移動させることから始めてみてください。
コメント