GitHub のリポジトリにドキュメントを入れる場合、大きく分けて
- README.md（および必要に応じてその他のドキュメント）をリポジトリに直接配置
- Wiki を使う
の 2 つのやり方があるが、基本的な機能（Markdown で書けて、GitHub サイト上での表示・編集が可能で、変更履歴も管理される）が同じだけに、どう使い分ければ良いのかというハテナが出て来たので、調べてみた。
機能的な違い
README.md と Wiki は基本的な機能は同じであるものの、確認できた範囲では以下のような違いがあった。
| README.md | Wiki | |
|---|---|---|
| 記述方法の簡単変更 | × | ○ |
| ページ一覧の自動作成 | × | ○ |
| サイドバー | × | ○ |
| フッター | × | ○ |
| ページの階層化 | ○ | × |
| 変更履歴管理 | リポジトリで管理 （全体＋ファイル別） | ファイル別のみ |
根本的には「README.md はリポジトリそのものの 1 ファイルにすぎない」という位置づけになっていて、ドキュメントに特化した Wiki との違いが生じているということだと思う。
「記述方法の簡単変更」というのは、「最初は Markdown で書いていたけど、途中で Textile に切り替えたくなった」という場合に、簡単に変更できるかという観点。
Wiki の場合、Web 上での編集時に Edit mode を選べるため簡単に変更できる。README.md の場合は、いったん README.md を削除してから新たに README.textile を作成すれば変更は可能（Code ページできちんとフォーマットして表示される）だが、Wiki と比べると一手間余計にかかる。
「ページ一覧の自動作成」は、Wiki の場合、特に何もしなくても、Wiki の右側に「Pages」という欄が表示されるようになる。逆に、これを消すことはできず、強制表示となる。
「サイドバー」「フッター」については、Wiki の場合、「_Sidebar」「_Footer」というページを作ることにより、常に Wiki の右側・下側にそのコンテンツを表示できる。
README.md の場合は、試しに _Sidebar.md _Footer.md というファイルをリポジトリに配置してみたが、README.md 表示の際にこれらのファイルは表示されなかった。
以上のように、Wiki にはドキュメントに特化したお手軽機能が備わっている。
一方で残念なのは、Wiki はページの階層化ができない点。ページ作成時に「A/B」のような命名をしてみても階層化されなかった。
README.md の場合はリポジトリそのものなので、リポジトリにフォルダーを作って新たな *.md（なり他のフォーマットのドキュメントなり）を配置すれば、ドキュメントも階層化できる。
「変更履歴管理」については、README.md はリポジトリそのものなので、リポジトリの変更履歴を見れば内容は一目瞭然。ドキュメントファイルを新規作成したり削除した場合も、リポジトリの変更履歴で確認できる。
Wiki の場合は変更履歴管理がページごとになっているので、それぞれのページの変更履歴は確認できるが、そもそもファイルが増えたり減ったりしたことを分かりやすく確認する手段は無い模様。
使い分け
機能的な違いを踏まえた上で、README.md（＋リポジトリ内ドキュメント）と Wiki をどのように使い分けるか？
正直なところ、決定的な方法は思いつかない。
1 ページで済む簡単なドキュメントならば、README.md だけで事足りるのは間違いない。
ではファイルが増えてきたら Wiki かというと、個人的にはそうでもないかなと思う。理由は、Wiki だとデザインが変更できないから。ファイルが増えるような本格的なドキュメントということであれば、Markdown お仕着せのデザインではなく、自分なりのデザインにしたい。
となると、HTML でちゃんとドキュメントを作ってリポジトリで管理、ということになる。README.md はごく簡単にして、詳しくは HTML ドキュメントをご覧ください、という誘導。
つまり、README.md（＋リポジトリ内ドキュメント）陣営オンリーになり、Wiki の出番は無い。
ただ、HTML ドキュメントの欠点は、GitHub サイト上で表示されないこと。http://htmlpreview.github.io/ で表示するか（現時点で CSS は反映されない）、あるいはリポジトリをいったんダウンロードしてもらうという手間が発生する。
その点 Wiki（でもリポジトリ上の *.md でもいいけど）はお手軽で良い。しかし、デザインを変更できないという他にも、ソフトウェア配布時にローカルで読めないという欠点もある。ネットに繋がっていないとドキュメントが読めないというのは困るシチュエーションがあるし、GitHub の都合で URL が変更されたりしたらリンク切れになってしまう。また、Wiki には「リンク先を別タブで開く」といった基本的な機能が備わっていなかったりする。
というわけで、暫定方針としては
- 簡単なドキュメント……README.md
- 本格的なドキュメント……HTML ドキュメントをリポジトリで管理
- Wiki は使わない
としようと思うが、課題はある、といった感じ。
他の人はどうしているか
使い分けを明確に示しているサイトが意外と無いのだが、
というような事例はあった。
