2026年9月23日、Michael Heapが「The GitHub wiki is an anti-pattern」と題した記事を公開した。GitHub Wikiを使い続けることがなぜ問題なのか、そして/docsフォルダへの移行がなぜ合理的な選択なのかを、具体的な理由とともに解説した内容だ。
CI/CDの普及とともに「ドキュメントをコードと同等に扱う」Docs as Codeという考え方が広まりつつある今、コードとは切り離されたGitHub Wikiという仕組みは、チーム開発の現場でじわじわと問題を露わにしてきた。Heapは「WikiかDocsフォルダか」という議論が約6ヶ月おきにコミュニティで繰り返されてきたと述べ、当初はどちらも有効な選択肢として書き始めたという。しかし書き進めるうちに気づいた。Wikiを使う理由は1つしかなく、使わない理由は山ほどある、と。
WikiのメリットはたったひとつだけでNO.2はない
Wikiの利点を正直に列挙すると、こうなる。
- リポジトリのどこからでもワンクリックでWikiにアクセスできる
- 以上。
「常にそこにある」というアクセスのしやすさだけが唯一のメリットだ。
Wikiを使ってはいけない7つの理由
一方、Wikiを使わない理由は具体的かつ多い。とりわけ最初の3つ——バージョン管理・クローン不可・レビュー不在——は、チーム開発の文脈では致命的になりうる。
- バージョン管理ができない。
/docsフォルダならコードと一緒にドキュメントもバージョン管理される。古いバージョンのドキュメントを参照したいとき、Wikiでは対応できない。 - ローカルに取得されない。リポジトリをクローンしてもWikiは含まれない。Wikiを別途クローンできる機能は存在するが、ほとんど知られていない隠し機能に近い。
- レビュープロセスから外れる。
/docsフォルダに置けば、コードと同様にプルリクエストでピアレビューを受けられる。 - CIによるLintができない。ValeなどのツールをGitHub Actionsで使えば、ドキュメントの文章品質を自動チェックできる。
- 使い慣れたツールが使えない。
/docsフォルダであれば、VSCodeのスペルチェック拡張など既存のエディタ環境をそのまま活用できる。 - ブランディングの自由度がない。Wikiはどれも見た目がほぼ同じで、デザインのカスタマイズがほとんどできない。
- 画像のアップロードに対応していない。結局、画像は別の場所に置かなければならない。
これらの問題は、個人プロジェクトでは表面化しにくい。しかしチームでの開発・レビュー・CI連携を前提にすると、Wikiの制約は次第に深刻になる。Docs as Codeの文脈ではドキュメントをコードと同等に扱うことが前提となるため、コードリポジトリと分離されたWikiという設計はその思想に根本から反している。
移行の具体的な手順
/docsフォルダをコードと同じリポジトリに置く運用がHeapの推奨だ。移行の手順は以下のとおり。
- ドキュメントをリポジトリの
/docsフォルダに置く。gh-pagesブランチは使わないこと（コードとのバージョン管理が切り離されてしまう）。 - GitHub Pagesでドキュメントを公開する。
- 始めたばかりであれば、just-the-docs（GitHub）テーマを使ってGitHubに自動ビルド・公開させるのが手軽。
- Hugoなどでカスタムワークフローをビルドしたいなら、actions-gh-pagesを使う方法もある。
- Wikiにはページを1つだけ残し、ホスティングされたドキュメントへのリンクを置く。
この構成は、新しいプロダクトを立ち上げる段階で最もコストパフォーマンスが高い選択肢だとHeapは述べている。ドキュメントが成長して単一フォルダに収まらなくなった時点で、独立したリポジトリへの移行を検討すればよい。その頃にはコントリビューターもリポジトリ内でドキュメントを扱うことに慣れているため、移行はスムーズになるはずだという。
コミュニティの反応
この記事はHacker Newsでも取り上げられ、活発な議論を呼んだ。「バージョン管理こそが決定的な理由」「コードと別になっているため、ドキュメントの存在自体に気づかないコントリビューターが多い」といった賛同の声が多く寄せられた一方、「小規模な社内ツールならWikiの手軽さで十分なケースもある」という反論もあった。
「常にそこにある」という利便性だけで選ばれてきたGitHub Wikiだが、チームでの開発・レビュー・CI連携を考えると、/docsフォルダの運用に軍配が上がるケースがほとんどだという見方が広まりつつある。
詳細はThe GitHub wiki is an anti-patternを参照していただきたい。
