In a nutshell

GitにおけるWikiは，プロジェクトのドキュメントを時系列で管理・共有できる仕組みである．READMEでは記述しきれない詳細情報を分けて整理でき，WebからもGit操作でも編集が可能．ソースコードとは別に，設計方針や手順書などの知識を蓄積・活用するのに適している．

はじめに

GitHubには，Wikiのタブが存在する．これについて，README等のドキュメントとは適切に使い分けたいと考えた．そこで，Wikiとその特徴や使い道について，調べて以下に纏めた．

予想される読み手

GitHubについて，初学者である
GitHubについて実務で利用している，する予定がある．

概要

GitにおけるWikiは，ソフトウェアプロジェクトやドキュメントを記述するための仕組みの一つ．主に，GitHubやGitLabなどのGitホスティングサービスで提供されている．WikiはGitのバージョン管理機能と組み合わされ，プロジェクトの技術的・運用的な情報を時系列で管理・編集することが可能である．Wikiはリポジトリごとに個別に用意される専用のGitリポジトリとして存在し，Markdown形式のファイルによってページが構成される．開発者やチームメンバーは，ウェブインターフェースからの編集はもちろん，ローカルにクローンして通常のGit操作でページを編集・管理することも可能である．

なぜWikiを利用するのか？

プロジェクトのドキュメントを整理・共有するため

Wikiは，READMEファイルに記述しきれないような詳細な情報を分けて記述するのに適している．たとえば，以下のような情報を明確に整理できる．

プロジェクトの目的や設計思想
開発・ビルド・テスト手順
各モジュールの仕様や使用例
チームでの運用ルールや開発方針

履歴管理・共同編集が可能

WikiもGitによって管理される為，変更履歴が残る．よって内容の追跡・差分確認が容易であり，複数人での共同編集が安全に行える．

Webインターフェースとコマンドラインの両方に対応

WikiはGitHubのブラウザ上と，コマンドラインからの通常のGit操作での編集の両方が可能．

ソースコード内のドキュメントとの違い

多くのプロジェクトでは，ソースコードのコメントやREADME.mdなどにドキュメントを記述する．しかし，Wikiはこれらとは明確に異なる目的と役割を担う．ソースコードに近いコメントやREADMEは必須であるが，それだけでは全体像や運用フローを網羅できない．Wikiはその補完として，開発と運用の橋渡しとなるような情報を整理するのに向いている．

比較項目	ソースコード内のドキュメント	Wiki
主な目的	関数・クラスなどの仕様を直接説明	プロジェクト全体の仕様・手順などの整理
管理単位	ソースファイルごと	ページ単位(独立した構成)
編集者	主に開発者	開発者に限らず，ドキュメント担当者や他職種も可能
内容の粒度	細かい実装に密接	高レベルな設計や方針，全体構成

どのようなときにWikiを使うべきか

Wikiの導入は必須ではないが，以下のような状況において特に有効である．

READMEが肥大化し，情報の整理が難しくなってきたとき
複数人で情報を記録・編集する必要があるとき
非開発者(例:マネージャー，ドキュメント担当)も情報を記載・共有したいとき
時系列で仕様やルールが変更されるプロジェクト
開発者が入れ替わる可能性があり，引き継ぎ情報を残したいとき

Wiki活用のベストプラクティス

情報の階層化とページ構成の整理

Wikiには階層的な構造がないため，リンクによるページ間の接続や，インデックスページ(目次)を自作することで可読性を高める．

命名規則の統一

ページ名やファイル名に明確なルール(例:命名にプレフィックスを使う，日付順，トピック別)を設けると，チームでの運用が容易になる．

編集履歴の活用

変更履歴はトラブルシューティングや情報の追跡に有用である．大きな変更を加える際は，変更理由や背景も記述しておくとよい．

タグやカテゴリの工夫(GitLabの場合)

GitLabでは，Wikiにカテゴリ機能があるため，情報を整理するために活用できる．GitHubでは，ページタイトルや見出しを工夫して代用する．

Wiki利用上の注意点

階層構造がない:大量のページを作成する場合は，リンク・インデックスページによる工夫が必要．
ブランチ運用に制限:Wikiには通常，mainブランチしか存在せず，細かい分岐管理には不向き．
非公開Wikiの制限:パブリックリポジトリではWikiも自動的に公開される点に注意(GitHubの場合)．

Wikiの導入方法

GitHubを例に，Wikiの導入手順を示す．

Web上での導入

対象のリポジトリを開く．上部メニューの「Wiki」タブをクリック．初回の場合，「Create the first page」と表示されるので，ページタイトルと内容を入力し，「Save Page」で作成完了．

ローカル環境での編集

Wikiは .wiki.git という名前の独立したリポジトリとして管理されているため，以下のようにクローン可能．
クローン後は，Markdownファイルを追加・編集し，通常のGit操作で更新する．

git clone https://github.com/<ユーザー名>/<リポジトリ名>.wiki.git

Summary

WikiはGitHubやGitLab上で使えるGit管理されたドキュメント機能である．
READMEに入りきらない詳細な情報の整理・共有に向いている．
編集履歴が残り，共同編集にも対応している．
ソースコード内のコメントとは異なり，プロジェクト全体の情報を扱う．
Webとローカル両方から編集でき，Markdown形式で記述可能．
情報の整理や命名ルールを明確にすると，チーム運用がスムーズになる．

References

GitHub Docs - Building communities/Using wikis/About wikis