GitHubのwikiはアンチパターンである
The GitHub wiki is an anti-pattern
GitHubでドキュメントを管理する際、wikiとdocsフォルダのどちらを使うべきかという議論が定期的に起きる。wikiの利点はリポジトリから1クリックでアクセスできることだけだが、docsフォルダならコードと同じバージョン管理ができ、プルリクエストでレビューも受けられ、GitHub Actionsでリントもできる。著者はdocsフォルダを使い、GitHub Pagesで公開することを推奨している。
GitHubでwikiを使うことはアンチパターンだと考えている。
HNでの議論
109- 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日時点のバージョンが取得できる、など。
- ericyd
反対だ。ドキュメントの変更にコードレビューを必須にするのは素晴らしいように聞こえるが、私の経験ではドキュメントの変更を人間にレビューしてもらうのは極めて難しい。まともなレビューなしのゴム印をもらうか（付加価値ゼロ、無駄な摩擦を追加するだけ）、あるいは実際にレビューしてもらうために何日も人を煩わせるかのどちらかだ。すべてはドキュメントのために！
私が想像する反論はこうだ：「同じPRでドキュメントとコードを同時に更新しよう！」それは、単一のコード片に厳密に結びつかない何かをドキュメント化したいときまではうまくいく。実際、最も有用なドキュメントは特定のコード片に関連付けられるというより、高レベルのシステムを記述するものだと思う。それにはコメントを使えばいい。対照的に、ドキュメントはいつでも誰でも簡単に編集できるべきだ。そうでなければ決して更新されない（どのようなシナリオでも永遠の課題だ）。
- mikeocool
私の経験では、開発環境のセットアップのようなもののドキュメントは、元々書いた人ではなく、2番目に開発環境をセットアップする人によって大幅に改善されることが多い。
その場合、ドキュメントがコード変更に関連付けられていないときは、そうした改善をドキュメントに取り込むのをできるだけ摩擦なくしたい。そうでなければ変更は行われないだろう。
個人的には、ドキュメントの更新を信じられないほど速く簡単にすることが、ドキュメント変更を完全なSDLCプロセスに通すことで得られる何よりもはるかに価値があるとわかった。もし誰かがレビューで共有するようなドキュメント変更へのフィードバックを持っているなら、代わりに自分でドキュメントを更新すればいい。
- codazoda
私はGitHubのアドオンは好きではないし、ここでの前提には同意するが...
もう一つ可能性が考えられる。ブラウザ経由でwikiに書く方が簡単なのだ。スマホで開いてドキュメントを編集できる。ブラウザで開いてドキュメントを編集できる。
デスクトップでは、リポジトリをプルしてエディタで開くのはほんの少し手間が増える（すでにそこにいるかもしれないが）、しかしそのほんの少しがドキュメントを書くのを止めるのに十分なことがある。私にとって、ドキュメントを書くことは実際にやるためには完全に苦痛であってはならない。
なぜPR、wiki、ディスカッション、プロジェクト、issueのようなアドオンが好きではないのか？それはそれぞれが程度の差こそあれベンダーロックインを導入するからだ。
- stephenlf
この記事に同意する。GitHubのwiki体験が特に使いやすいと感じたことは一度もない。問題があるわけではないが、単純な/docsフォルダ以上に便利というわけではない。そしてそこから、/docsをGitHub Pagesに変えるのはほとんど些細なことだ。同じ手間で、はるかに良い最終製品が得られる。
wikiは通常、分散された匿名の編集を意味する。この機能はgitによってすでに部分的にカバーされている。
- sigvef
あまり知られていないが、GitHubのwikiは実際には別の「隠された」リポジトリに支えられており、リポジトリのURLに.wikiを追加することでアクセスできる。例えば https://github.com/lionleaf/dwitter.wiki.git のように。
どうやらCI的なこともできるらしい。それでも、TFAやこのスレッドで概説されている他の理由から、お勧めはしない。
- a4isms
2番目の段落は私の確証バイアスをうまく刺激した：
この記事の最初のバージョンは「GitHubプロジェクトにはwikiかdocsフォルダのどちらかを使える、どちらも有効な選択だ」で始まっていたが、書いているうちに、wikiを使う理由はただ一つしかなく、wikiを使わない理由はもっとたくさんあることに気づいた。実際あまりにも多く、GitHubでwikiを使うことはアンチパターンだと考えている。
McCullochの言葉「書くことは考えることだ」の非常にわかりやすい例だ。