こんにちは！昨年の秋、少し時間を取ってGitのドキュメントに取り組むことにしました。オープンソースのドキュメントに携わりたいとずっと思っていて――普段は、何かのドキュメントをもっと改善できると思ったら、ブログ記事やZINEなどを書くようにしています。でも今回は、公式ドキュメント自体を少し改善できないだろうかと考えたのです。

そこでMarieと一緒に、Gitのドキュメントにいくつか変更を加えました！

Gitのデータモデル

ドキュメントの作業をしばらく続けるうちに、Gitのドキュメントでは「object」「reference」「index」といった用語が頻繁に使われているのに、それらが何を意味するのか、あるいは「commit」や「branch」といった他の中心的な概念とどう関係しているのかが、きちんと説明されていないことに気づきました。そこで、新しい「データモデル」のドキュメントを書くことにしたのです！

データモデルは今のところこちらで読めます。いずれ（次のリリースの後でしょうか？）Gitのウェブサイトにも掲載されると思います。

これにはとてもワクワクしています。Gitがコミットやブランチのデータをどのように整理しているかを理解することは、長年にわたってGitの仕組みを考えるうえで本当に役立ってきたからです。そして、正確でコンパクトな（わずか1600語！）データモデルの解説があることは重要だと思っています。

ただ、「正確に」という部分は思ったほど簡単ではありませんでした。Gitのデータモデルの基本は知っているつもりでしたが、レビューの過程で新たな詳細をたくさん学び、かなり多くの修正が必要になりました（例えば、マージコンフリクトがステージングエリアにどのように保存されるかなど）。

git push、git pullなどの更新

それから、Gitの主要なmanページの導入部分を更新する作業にも取り組みました。すぐに気づいたのですが、「自分の判断でとにかく改善してみる」というやり方ではうまくいきません。なぜメンテナたちが、私の書いたバージョンの方が優れていると信じてくれるでしょうか？

オープンソースのドキュメント変更について議論する際によく見かける問題があります。ソフトウェアに詳しい2人が、ある説明が分かりやすいかどうかについて議論するのです（「Xという説明が良いと思う！」「いや、Yの方が良いよ！」といった具合に）。

これはあまり生産的ではないと思います（あるソフトウェアの上級者は、その説明が初心者にとって分かりやすいかどうかを判断するのが極端に苦手なことで知られています）。そこで、manページの問題点をもう少し証拠に基づいて見つけ出す方法が必要でした。

テストリーダーに問題点を見つけてもらう

Mastodonでテストリーダーを募り、現在のドキュメントを読んで、分かりにくい点や疑問に思ったことを教えてもらいました。約80人のテストリーダーがコメントを寄せてくれて、本当に多くのことを学べました！

たくさんの素晴らしいフィードバックが寄せられました。例えば次のようなものです。

• 理解できなかった用語（pathspecとは何か？「reference」は何を意味するのか？「upstream」はGitで特定の意味を持つのか？）
• 分かりにくい具体的な文章
• 追加してほしい内容の提案（「私はいつもXをやっているので、ここに含めるべきだと思う」）
• 不整合（「ここではXがデフォルトであるように書かれているが、別の場所ではYがデフォルトであるように書かれている」）

テストリーダーの多くは、少なくとも5〜10年はGitを使ってきた人たちでしたが、これはとてもうまくいったと思います。5年以上も日常的にGitを使ってきた人たちのグループが、ある文章や用語を理解不可能だと感じるのであれば、そのドキュメントはより分かりやすく更新すべきだと主張しやすくなるからです。

この「ソフトウェアのユーザーに既存のドキュメントについてコメントしてもらい、見つかった問題を修正する」というやり方はとてもうまくいったと感じていて、今後また試してみるのが楽しみです。

manページの変更点

最終的に、以下の4つのmanページを更新しました。

• git add（変更前、変更後）
• git checkout（変更前、変更後）
• git push（変更前、変更後）
• git pull（変更前、変更後）

個人的に最も興味深かったのはgit pushとgit pullの変更です。これらのページの導入部分を更新しただけでなく、最終的に次のような内容も書くことになりました。

• 「upstream branch」という用語が何を意味するのかを説明するセクション（以前はあまり説明されていませんでした）
• 「push refspec」とは何かを整理して説明した記述

そうした変更を通じて、オープンソースのドキュメントを維持するのがどれほど大変なことかを実感しました。分かりやすく、かつ正確に書くのは簡単ではなく、時には妥協もしなければなりませんでした。例えば、「git pushは、push.defaultの設定によっては、現在のブランチにupstreamを設定していないと失敗することがあります」という一文は少し曖昧ですが、「depending（〜によって）」が正確に何を意味するのかの詳細は非常に複雑で、それを解きほぐすのは大きなプロジェクトになるからです。

Gitへのコントリビュートのプロセスについて

Gitの開発プロセスを理解するのには少し時間がかかりました。ここで詳しく説明するつもりはありません（それだけで別の記事が一本書けてしまいそうです！）が、いくつか簡単にメモしておきます。

• GitにはDiscordサーバーがあり、コントリビュートを始めるための「my first contribution」チャンネルがあります。Discordでは皆さんがとても温かく迎えてくれました。
• 私はすべてのコントリビュートにGitGitGadgetを使いました。これにより、慣れ親しんだワークフローであるGitHubのプルリクエストを作成でき、GitGitGadgetがそれをGit開発者が使っている仕組み（パッチを添付したメール）に変換してくれました。GitGitGadgetは素晴らしく機能し、Gitでメール経由でパッチを送る方法を学ばずに済んだことをとてもありがたく思いました。
• それ以外は普段使っているメールクライアント（Fastmailのウェブインターフェース）でメールに返信し、メーリングリストの慣習に従ってテキストを80文字で折り返すようにしました。

また、lore.kernel.orgにあるメーリングリストのアーカイブは使いにくいと感じたので、長いスレッドを読みやすくするために自分で自作のgit list viewerをさっと作りました。

多くの方々にコントリビュートのプロセスの案内や変更のレビューでお世話になりました。Emily Shaffer、Johannes Schindelin（GitGitGadgetの作者）、Patrick Steinhardt、Ben Knoble、Junio Hamanoをはじめ、皆さんに感謝します。

（Mastodonでのコメント機能を試しています。コメントはこちらでご覧いただけます）