話題
2026年9月23日
「GitHub Wikiはアンチパターン」海外エンジニアの間で議論に
「GitHubのWikiはアンチパターンだ」とするブログ記事をきっかけに、Hacker Newsで技術者たちの議論が広がった。元記事は、ドキュメントはWikiではなくリポジトリ内の「/docs」フォルダで管理すべきだと主張する内容。コメント欄では、Wikiなら誤字修正のような些細な編集がPRやレビューなしにできるという利点と、/docsならコードの変更と同時に差分が見えるため文書の陳腐化を防げるという指摘がぶつかった。GitHubのWikiが実は非公開のGitリポジトリであることや、公開編集可能なWikiは検索エンジンにインデックスされないという仕様も話題に上った。
GitHubのWikiはアンチパターンだ
出典: michaelheap.com / 元記事はこちら
5
海外の名無しさん
2026-09-23 14:38
Wiki側の見落とされているメリットがあると思う。些細な編集は本当に些細で済む。docsフォルダ内の誤字修正でさえPR、承認、CIが必要になる。つまりコードエディタとGitに慣れている人にしかドキュメントへの貢献者を絞れないということだ。これは一つの判断ではある
8
海外の名無しさん
2026-09-23 14:30
なぜみんなdocsフォルダから『生成』するのか昔から理解できない。Markdownで書いてあるなら（大抵そうだが）GitHub上ですでにちゃんとレンダリングされているのに。それとも別の場所にも公開しているから？
10
海外の名無しさん
2026-09-23 14:33
同意だけど、ドキュメントだけの更新にも儀式が必要なのが唯一の不満。レビューとCIが必要になる。レビュー自体は大抵良いことだけど（ドキュメントは正確であってほしいから）、うちのチームだと2日くらいかかる（こう書いてて、それは多分うちのせいだと気づいた）。CIについては、Markdownのみの変更はスキップするステップを全アクションに追加した。もっと良い方法がある人いる？
12
海外の名無しさん
2026-09-23 13:30
自分にとって一番大きいのは、Wikiの編集はコードレビューを経ないという点。だからドキュメントは静かに陳腐化していく。一方/docsへのPRなら、少なくともコードの変更と並んで差分に表示される
32
海外の名無しさん
2026-09-23 13:37
>>12 その通り。それにエージェントがどこにでもいる今の時代、ドキュメントはもっと頻繁に更新・チェックできる。Wikiに置いてある場合でも、ローカルにクローンしてAGENTS.mdにドキュメントの場所を書いておけば対応できるけど、結局は別のリポジトリを扱うことになる。功績は認めるべきで、当時としては革命的（ありがたい存在）だったけど、今となっては/docsの方が良いと思う
33
海外の名無しさん
2026-09-23 13:51
>>12 話がつながらないんだけど。コードレビューという摩擦を加えることが、どうして陳腐化を減らすの？
13
海外の名無しさん
2026-09-23 14:17
Wikiには最低限ディレクトリ機能があって、構造化しやすくしてほしかった。並行してメンテナンスするメジャーバージョンにも対応できるように
14
海外の名無しさん
2026-09-23 13:53
細かい指摘だけど、『/docsフォルダを使うのが労力対効果の比率が一番高い』というのは、一番低い、または効果対労力の逆じゃない？
15
海外の名無しさん
2026-09-23 13:37
興味深い。ちょうど自分のプロジェクトの一つにWikiを追加したところ。ドキュメント用ではなく、すでにリポジトリ内にドキュメントがあるので。むしろ、Issueとして立てるほどまとまっていない（あるいは価値があるか分からない）アイデアや実験のための公開メモ帳として使っている
16
海外の名無しさん
2026-09-23 13:42
ここで触れられていない一番大きな理由があると思っていた。GitHubがrobots.txtで/*/wiki*をDisallowに設定していたこと。でも今は変わったのかもしれない。今のhttps://github.com/robots.txtには見当たらない
34
海外の名無しさん
2026-09-23 13:51
>>16 公開編集可能な場合はインデックスされない
17
海外の名無しさん
2026-09-23 14:10
GitLabだとWikiは単に別のGitリポジトリになっている。GitHubは違うの？
35
海外の名無しさん
2026-09-23 14:14
>>17 そう、その通り。ただし隠れたGitリポジトリで、GitHubのツール類は一切使えない
18
海外の名無しさん
2026-09-23 14:25
（2022年の記事）
19
海外の名無しさん
2026-09-23 14:18
そう、他の部分も同じ。今日もまた障害が起きていて、CIが止まってる。待ってる間にWikiでも読んでろってことかな？ https://www.githubstatus.com/
21
海外の名無しさん
2026-09-23 14:21
『お前が引き取れ』ってことだな、覚えておくよ！
22
海外の名無しさん
2026-09-23 13:58
Forgejoでは、Wikiは単なる別リポジトリだから、そこでバージョン管理ができる
24
海外の名無しさん
2026-09-23 13:51
エージェントにとっても、バージョン管理された/docsの方がコードベースの変更内容を理解しやすいだろう
25
海外の名無しさん
2026-09-23 13:54
>>4 なぜこれが単なる/docsディレクトリより簡単で効果的なの？
37
海外の名無しさん
2026-09-23 13:58
>>25 親コメントがその答えにリンクしてるよ
26
海外の名無しさん
2026-09-23 13:57
>>4 Fossilが一番いい。SQLiteが使ってる
38
海外の名無しさん
2026-09-23 14:36
>>26 FossilはSQLiteのために書かれた。ちょうどGitがLinuxのために書かれたのと同じように。もっと多くのプロジェクトが使わないのは本当に残念。ソーシャル機能やPR、CIなどを備えたFossilバックエンドのGitHub対抗サービスがあれば、かなり人気が出ると思う
29
海外の名無しさん
2026-09-23 13:46
>>11 それは`docs`フォルダ（または適切な命名パターン）への変更だけマージゲートを緩めれば簡単に解決できる。コマンドラインを使いたくなければ、Web上でライブ編集することもできる
30
海外の名無しさん
2026-09-23 14:11
>>11 ドキュメントの修正や改善って、結局ただのバグ修正では？
31
海外の名無しさん
2026-09-23 13:44
>>11 docsフォルダへの変更はコードレビュー不要にする自動化や設定を組める
39
海外の名無しさん
2026-09-23 14:18
>>27 そう、GitHubの『Wiki』を自由編集可能に設定することはできるけど、それはデフォルトじゃないし、ほとんどのWikiはそうなっていない
40
海外の名無しさん
2026-09-23 14:00
>>33 コードの変更だけでドキュメントの変更が無い（あるいはその逆）というのは見分けがつく
41
海外の名無しさん
2026-09-23 13:53
>>34 あと、対象リポジトリには500以上のスターも必要 https://docs.github.com/en/communities/documenting-your-proj…
42
海外の名無しさん
2026-09-23 14:40
>>41 それに『公開編集不可』であることも必要。つまり、精神的にはもうWikiではない
この話題の背景と論点
元記事は2022年に書かれたものが今回改めて話題になった経緯があり(no.18)、GitHubの仕様は投稿当時から変わっている可能性がある点には注意したい。実際、no.16のようにrobots.txtでWikiを検索エンジンから除外する設定が今は見当たらないという指摘も出ている。スレッドで意見が割れたのは、コードレビューを挟む「/docs」方式が本当に文書の陳腐化を防ぐのかという点で、レビューの遅さがかえって更新を妨げるという指摘(no.10, no.33)と、差分がコードと並んで可視化されることが品質維持につながるという指摘(no.12)が対立した。またGitLabやForgejoのWikiも同様に独立したGitリポジトリとして実装されている点、SQLiteが採用する分散型バージョン管理システム「Fossil」への言及など、Git以外の選択肢にも話が広がった点は本文だけでは見えにくい背景として押さえておきたい。
※本記事は5ch(Hacker News)スレッド「The GitHub wiki is an anti-pattern」より抜粋・要約して構成しています。
この記事のリアクション
まだコメントはありません。