GitHubのWikiはアンチパターンである

「GitHubでWikiを使うべきか、それとも/docsフォルダを使うべきか」という議論は、およそ6ヶ月ごとに持ち上がります。Shawn Wang氏の3回の警告ルールに従い、私もこの件について何か書き留めておくべき時が来たと思いました。 この投稿の最初のバージョンは、「GitHubプロジェクトでWikiまたは/docsフォルダを使用できます。どちらも有効な選択肢です」という言葉で始まりましたが、書き進めるうちに、Wikiを使用する理由は1つしかなく、Wikiを使用しない理由は数多くあることに気づきました。その数は非常に多く、GitHub上のWikiの使用はアンチパターンだと考えています。 Wikiを使用する利点から始めましょう。 リポジトリ内のどこからでも、ワンクリックでWikiの内容にアクセスできます。 2つ目はありません。 本当に、私が発見できたWikiの唯一の利点は、それが常にあるということです。 Wikiを使用しない理由についてはどうでしょうか？ /docsフォルダを使用すると、ドキュメントはコードと共にバージョン管理されます。古いバージョンを使用する必要がある場合、ドキュメントは簡単に見つかります。 リポジトリをクローンしても、ドキュメントはローカルで利用できません（Wikiは別途クローンできますが、これは隠し機能です）。 ドキュメントの編集は、コードと同じように扱われます。プルリクエストプロセスを通じて、完全なピアレビューが行われます。 Valeのようなツールを使用して、GitHub Actionsでドキュメントをリントできます。 人々は、使い慣れたツール（例: スペルチェック付きのVS Code）で作業できます。 Wikiはブランディングの機会が限られています。ほとんどすべて同じように見えます。 Wikiは画像のアップロードをサポートしていないため、いずれにしても画像をどこか別の場所に配置する必要があります。 これで、コードの隣にドキュメントを配置するという考えに納得したら、人々がそれらを簡単に見られるようにするにはどうすればよいでしょうか？ ドキュメントをリポジトリの/docsフォルダに追加します。ドキュメントがコードと共にバージョン管理されるのを妨げるため、gh-pagesブランチを使用しないでください。 ドキュメントを公開するためにGitHub Pagesビルドを設定します。 始めたばかりの場合は、just-the-docsテーマを使用し、GitHubにドキュメントのビルドと公開を任せることをお勧めします。 独自のワークフローを構築したい場合（例: Hugoを使用）、このGitHub Actionを使用してドキュメントを公開できます。 ホストされているドキュメントに人々を誘導する単一のWikiページを追加します。 /docsフォルダを使用することは、新しい製品を開発している間、最も高い労力対効果のオプションです。ある時点で、ドキュメントは単一のフォルダの容量を超え、その時点ではすべてが不確かになります。独自のビルドプロセス、プルリクエストレビューガイドライン、およびその他の多くの要素を持つ別のリポジトリが必要になります。その時点で、人々はすでにリポジトリ内のドキュメントを扱うことに慣れており、/docsから独自のレポジトリへの移行は、コントリビューターにとってシームレスになるはずです。 同意するかしないかにかかわらず、Twitterであなたの考えを聞かせていただければ幸いです。