/docs を勧める理由GitHubのプロジェクトで、ドキュメントを wiki に置くべきか、それともリポジトリ内の /docs フォルダに置くべきか。この記事は、その定番の悩みにかなりはっきりした答えを出しています。筆者は wiki の利点を認めつつも、実際には欠点のほうが多く、GitHub の wiki はアンチパターンだとまで言い切ります。単なる好みの話ではなく、利用者と保守者の両方にとってどちらが扱いやすいか、という視点で整理しているのがポイントです。
/docs を選ぶのか元記事は、GitHub プロジェクトで「wiki を使うべきか、/docs フォルダを使うべきか」という議論が半年おきくらいに出てくる、と前置きしたうえで、自分の考えを明文化したものです。筆者は当初、「wiki でも /docs でもどちらも正しい選択肢」と書き始めたそうですが、書き進めるうちに見方が変わり、wiki を使う理由はほぼ一つしかないのに、使わない理由はたくさんあると結論づけています。そのため、GitHub の wiki はアンチパターンだと位置づけました。
筆者が認める wiki の利点は、リポジトリのどこからでも一クリックで内容にたどり着けること、そして「いつでも存在している」ことくらいです。だがそれ以外の点では /docs のほうが優れていると主張します。まず、/docs に置けばドキュメントはコードと同じようにバージョン管理されるので、古い版を参照する必要があるときに見つけやすい。逆に wiki は、リポジトリを clone したときにローカルには含まれず、必要なら wiki を別途 clone しなければならないが、それは目立たない機能だと指摘しています。
さらに、/docs に置いた文書はコードと同じ PR の流れに乗せられます。つまり、編集は pull request でレビューされ、GitHub Actions と組み合わせて Vale のようなツールで文書の lint もできる。利用者にとっても、普段から使い慣れた vscode と spellcheck のような道具で作業できるので、学習コストが低いというわけです。対して wiki は見た目の自由度が低く、どれも似たような外観になりやすい。しかも画像のアップロードに対応していないため、画像は別の場所に置く必要が出てきます。
では、/docs を公開するにはどうするのか。筆者は、まずドキュメントをリポジトリ内の /docs フォルダに置き、gh-pages ブランチは使わないほうがよいと言います。gh-pages を使うと、コードとドキュメントの版が分かれてしまうからです。そのうえで GitHub Pages の build を設定して公開し、始めたばかりなら just-the-docs テーマを使って GitHub にビルドと公開を任せるのがおすすめだと述べています。自前のワークフローを組みたいなら、たとえば Hugo を使い、GitHub Action で公開する方法もあると紹介しています。加えて、wiki 側には一枚だけ案内ページを置き、実際の文書はホストされたページへ誘導すればいい、としています。
最後に筆者は、/docs は新しいプロダクトを育てている途中では、手間に対する見返りが大きい選択だと締めています。ただし、ドキュメントがやがて一つのフォルダに収まらない規模になったら話は別で、別リポジトリに移して独自の build process や review guideline を持つ段階が来る。そのときには、すでに人々は「ドキュメントはリポジトリの中で扱うもの」という感覚に慣れているので、/docs から専用リポジトリへの移行も自然に進むだろう、という見立てです。
この記事で面白いのは、wiki を完全否定しているというより、「短距離走では便利に見えるが、長距離になると不利が出る」と整理しているところだと思う。利用者が一回だけ読むなら、クリック数の少なさは確かに魅力だ。けれど、文書はたいてい一回読まれて終わりではない。更新され、レビューされ、古い版を参照され、コードと一緒に直される。そこまで含めて考えると、/docs に置くほうが自然だという筆者の感覚には納得がある。
特に刺さるのは、ドキュメントをコードと同じ PR に乗せるという話だ。これは単なる運用の好みではなく、品質管理の話に近い。コードだけレビューされ、説明文は誰にも見られない、という状態はわりと起きがちだが、ユーザー体験を左右するのはむしろ文書のほうだったりする。筆者が lint や spellcheck に触れているのも、ドキュメントを「おまけ」ではなく、メンテ対象として扱えと言っているように読める。
/docs の組み合わせは、移行しやすさが強い筆者は gh-pages ブランチを避けるべきだと言うが、ここには実務的な感覚がよく出ていると思う。公開だけを先に切り離すと、見た目は整っても、どの版の文書がどの版のコードに対応しているのかが分かりにくくなる。ソフトウェアの文書で困るのは、きれいさより整合性が失われることだ。/docs を起点に GitHub Pages で出す形なら、少なくとも「コードの近くにある」という原則を守りやすい。
しかも筆者は、最終的には専用リポジトリに分ける可能性まで見ています。ここが重要で、最初から大きな仕組みを作るのではなく、成長段階に合わせて段階的に移す発想です。新規プロダクトでは、重たいドキュメント基盤を作るより、まずはコードの横に置いて回し始めるほうが現実的だろう。後から大きくなったら分離すればいい。この記事はその順番をかなりうまく言語化していると思う。
wiki の問題は、単独作業なら見えにくいのに、人数が増えるほど表面化することだと思う。画像が別置きになる、ローカルに入らない、レビューの流れから外れやすい、見た目が差別化しにくい。これらは一つひとつは小さくても、チームで保守する文書では積み重なる。結果として「読む側は見つけにくく、直す側は雑に扱いやすい」構造になりがちだ。筆者が wiki をアンチパターンと呼ぶのは、その小さな不便が将来の大きな摩擦になると見ているからだろう。
一方で、wiki には「すぐ置ける」「どこからでも入れる」という気軽さもある。だから完全に不要とは言い切れないが、筆者の立場はかなりはっきりしている。少なくとも新しいプロダクトを始める段階で、最初から wiki を主戦場にする理由は薄い、ということだ。文書は後回しにされやすいからこそ、最初の置き場所が大事になる。そこをリポジトリの外に逃がすと、あとで整えるときに面倒が増える。この記事は、その面倒を先回りして避けようとしている。