GitHub Wikiはしばしばアンチパターンとして批判されますが、有用な問いはより限定的です。つまり、いつ別のWikiを使うことがドキュメントの保守を容易にし、いつそれが回避可能な運用上の摩擦を生むのかという点です。Michael Heapの投稿「The GitHub wiki is an anti-pattern」は、ソフトウェア保守の観点から、ドキュメントは通常、それが説明するコードと同じ場所に属すべきであると主張しています。これは強力なデフォルト設定ではありますが、普遍的なルールではありません。
中心的な違いはプロバナンス（由来）にあります。Wikiは独自の履歴、権限、レビューの慣習、および公開パスを持つ独立したGitリポジトリです。一方、アプリケーションリポジトリ内の`docs`ディレクトリは、ドキュメントの変更を、それを必要とするコードの変更と並べて配置することができます。これはすべてのドキュメント編集を自動的に改善するわけではありませんが、プルリクエスト、コードレビュー、および後のデバッグの際に、動作とドキュメントの関係を調査しやすくします。
主な反論は摩擦です。ブラウザで編集可能なWikiは、特にリポジトリ内で作業していない人にとって、小さな修正のコストを下げます。これは、ドキュメントの品質が人々が段階的な更新を行うかどうかに依存するため重要です。すべての誤字に対してクローン、ブランチ、プルリクエスト、承認、またはCIの実行を要求することは、有用な編集を妨げる可能性があります。実用的な教訓は、すべてのドキュメントがコードレビューのパイプラインを通過しなければならないということではなく、チームがどのドキュメントの変更にレビューが必要で、どれをより軽量なパスで処理できるかを意図的に選択すべきであるということです。
したがって、`docs`を好む最も強力な理由は、イデオロギー的な純粋さではありません。バージョン管理されたドキュメントは、プロジェクトの他の部分と同じツールを使用してテスト、ビルド、検索、および変更ができるという点です。リポジトリは、ソースをWikiに移動することなく、GitHub Pagesや他の静的サイトビルドを通じてドキュメントを公開することもできます。提供された資料は特定のビルド構成を確立するものではありませんが、一般的な比較を支持しています。つまり、Wikiはアプリケーションリポジトリから分離されているのに対し、ツリー内のドキュメントディレクトリはリポジトリのワークフローに直接参加できるということです。
スケールは異なる問いをもたらします。Heapの投稿では、ドキュメントは最終的に単一のフォルダを超えて成長し、独自のビルドプロセスを持つ別のリポジトリを必要とする可能性があると述べています。提供された証拠は正確な閾値を特定していませんし、その移行を必然的なものとして扱う理由もありません。大規模なドキュメントセットは、個別の所有権、ナビゲーション、ローカライズ、または公開インフラを必要とするかもしれませんが、それらのニーズは、専用のドキュメントリポジトリ、ドキュメントサイト、またはより構造化されたモノレポで満たすことができる場合があります。重要な点は、移動の理由を単にファイル数が多いことと切り離すことです。
セキュリティとガバナンスも異なります。Wikiの権限と編集履歴はGitHubのWikiおよびリポジトリのコントロールを通じて管理されますが、ツリー内のドキュメントはリポジトリのコントリビューションおよびレビューのルールを継承します。どちらのモデルも本質的に安全または不安全ではありません。運用上のリスクは、利便性だけでワークフローを選択し、その後、ドキュメントの変更がレビュアーに見えず、再現が困難であるか、あるいはコードとは異なるグループによって保守されていることに気づくことです。チームはそれらの責任を明確にするべきです。
ほとんどの製品およびエンジニアリングドキュメントにとっての最良のデフォルトは、小さな修正のための軽量なプロセスを備えたバージョン管理された`docs`ツリーです。Wikiは、リリースエンジニアリングから意図的に分離されたメモ、別のチームによって保守されるドキュメント、または正式なレビューが逆効果となるような迅速な共同キャプチャには、依然として妥当な選択肢となり得ます。決定はドキュメントのライフサイクルに従うべきです。つまり、誰がそれを所有し、どのように変更され、どのようにレビューされ、そして読者が使用しているソフトウェアと一致するバージョンをどのように見つけるかという点です。