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

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

「GitHubでWikiを使うべきか、それともdocsフォルダを使うべきか？」という議論は半年ごとに持ち上がりますが、Shawn Wangのスリー・ストライクス・ルールに従って、私もそろそろ何かを書き留める時期だと考えました。

この記事の最初のバージョンは「GitHubプロジェクトでは、Wikiまたはdocsフォルダのどちらを使用することもできます。どちらも有効な選択肢です」という言葉で始まりましたが、書き進めるうちに、Wikiを使用する理由は1つしかなく、Wikiを使用しない理由はそれ以上にたくさんあることに気づきました。それほど多くあるため、私はGitHubでWikiを使用することはアンチパターンであると考えています。

Wikiを使用する利点から始めましょう。

1. リポジトリ内のどこからでもワンクリックでWikiの内容にアクセスできます。
2. ありません。2つ目はありません。

本当に、私が発見できたWikiを使用する唯一の利点は、それが常にあるということです。

では、Wikiを使用しない理由はどうでしょうか？

1. /docsフォルダを使用すると、ドキュメントはコードと共にバージョン管理されます。古いバージョンを使用する必要がある場合、ドキュメントは簡単に見つかります。
2. リポジトリをクローンしたときに、ドキュメントはローカルで利用できません（Wikiは個別にクローンできますが、これは隠し機能です）。
3. ドキュメントの編集は、コードと同じ扱いを受けます。プルリクエストプロセスを通じて完全なピアレビューが行われます。
4. Valeのようなツールを使用して、GitHub Actionsでドキュメントをリントできます。
5. 人々は、使い慣れたツール（例: スペルチェック付きのvscode）で作業できます。
6. Wikiはブランディングの機会が限られています。どれもほとんど同じように見えます。
7. Wikiは画像のアップロードをサポートしていないため、結局画像をどこか別の場所に置く必要があります。

コードと共にドキュメントを保持するという考えに納得したら、人々がそれらを簡単に見られるようにするにはどうすればよいでしょうか？

1. ドキュメントをリポジトリの/docsフォルダに追加します。ドキュメントがコードと共にバージョン管理されるのを妨げるため、gh-pagesブランチは使用しないでください。
2. ドキュメントを公開するためにGitHub Pagesビルドを設定します。
   • 始めたばかりの場合は、just-the-docsテーマを使用し、GitHubにドキュメントのビルドと公開を任せることをお勧めします。
   • 独自のワークフロー（例: Hugoを使用）をビルドしたい場合は、このGitHub Actionを使用してドキュメントを公開できます。
3. ホストされているドキュメントに人々を誘導する単一のWikiページを追加します。

/docsフォルダを使用することは、新しい製品を構築している間、最も高い労力対効果が得られるオプションです。いつかドキュメントが単一のフォルダの容量を超えた場合、すべてが保証されなくなります。独自のビルドプロセス、プルリクエストレビューガイドライン、およびその他の多くの要素を持つ別のリポジトリが必要になるでしょう。その時点では、人々はすでにリポジトリでドキュメントを扱うことに慣れており、/docsから独自のレポへの移行は、コントリビューターにとってシームレスになるはずです。

同意するかしないかにかかわらず、Twitterであなたの考えを聞かせていただけると嬉しいです。