GitHubのwikiはアンチパターンである
The GitHub wiki is an anti-pattern
GitHubでドキュメントを管理する際、wikiとdocsフォルダのどちらを使うべきかという議論が定期的に起きる。wikiの利点はリポジトリから1クリックでアクセスできることだけだが、docsフォルダならコードと同じバージョン管理ができ、プルリクエストでレビューも受けられ、GitHub Actionsでリントもできる。著者はdocsフォルダを使い、GitHub Pagesで公開することを推奨している。
GitHubでwikiを使うことはアンチパターンだと考えている。
HNでの議論
89- gwking
最後の段落にはこう書かれている：
> ある時点でドキュメントは単一のフォルダには収まらなくなり、そうなればもう何も保証できない。独自のビルドプロセスを持つ別のリポジトリが欲しくなるだろう...
私の疑問は、なぜこれが前提とされているのか？ ある程度の規模になったら、ドキュメントとコードをバージョン管理下で一緒に置いておくのはそんなに難しいことなのか？ もしそうなら、具体的な問題は何で、原因は何なのか？
こう尋ねるのは、gitでプロジェクトを整理するために試してきた様々な方法に、これまであまり満足したことがないからだ。最近は、変更がより局所化されるように、ソース、テスト、ドキュメントを同じツリーにまとめておくようにしている。これは物事を把握するのに役立っているように思える。特に、あちこちで変更を加えたがるコーディングエージェントを使う場合には。彼らが同じアイデアを複数の場所（エージェント指示、ドキュメント、docstring、ヘルプ文字列、コメント）で繰り返す傾向があるのは、特に問題だと感じている。
- chungy
Fossil（https://fossil-scm.org/home/doc/trunk/www/index.wiki）はこれをかなりうまく解決している。ドキュメントをファイルとして、あるいは特別なwiki名前空間に置くことができ、どちらもバージョン管理され、リポジトリのクローンにはすべてが含まれる。さらに良いことに、ツリー内のドキュメントファイルは、専用のwiki名前空間とまったく同じようにレンダリングされ、閲覧できる。
そこにリンクされているホームページのURL自体が例になる："trunk"はチェックイン名（https://fossil-scm.org/home/doc/trunk/www/checkin_names.wiki）で、"trunk"ブランチの最新チェックインを指している。これを他の参照に置き換えれば古いバージョンを取得できる。例えば、version-2.20とすればバージョン2.20のドキュメントが、2015-03-14とすれば2015年3月14日のバージョンが得られる、など。
- WCSTombs
完全に同意する。ドキュメントがソースコードと同じリポジトリにあれば、少なくともドキュメントをコードとアトミックに同期させておくことができる。これを可能にする他の方法はない（Git submodulesを使う構成は除くが、それは手間が増えるだけで同じことだ）。そして、それは即座に致命的な問題となるべきだ。
コードを反映するようにドキュメントが更新されることは、すべてのプルリクエストに対するブロッキング制約にできる（そして私の意見では、そうあるべきだ）。
- codazoda
GitHubのアドオンは好きではないし、ここでの前提には同意するが...
もう一つ可能性が考えられる。ブラウザ経由でwikiに書く方が簡単なのだ。スマホで開いてドキュメントを編集できる。ブラウザで開いてドキュメントを編集できる。
デスクトップでは、リポジトリをプルしてエディタで開くのはほんの少し手間が増える（すでにエディタを開いているかもしれないが）、しかしそのほんの少しの手間が、ドキュメントを書くのを止めさせるのに十分なことがある。私にとって、ドキュメントを書くことは、実際にやるためには完全に苦痛なくらいでなければならない。
なぜPR、wiki、ディスカッション、プロジェクト、イシューといったアドオンが好きではないのか？ それはそれぞれが程度の差こそあれベンダーロックインを生むからだ。
- stephenlf
この記事に同意する。GitHubのwiki体験が特に使いやすいと感じたことは一度もない。問題があるわけではないが、単純な/docsフォルダ以上に便利というわけでもない。そしてそこから、/docsをGitHub Pagesに変えるのはほとんど些細なことだ。同じくらいの手間で、はるかに良い最終成果物が得られる。
wikiは通常、分散された匿名の編集を意味する。この機能はgitですでに部分的にカバーされている。