こんにちは！この秋、私は 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 がデフォルトであることを示唆している」）

ほとんどのテストリーダーは Git を少なくとも5〜10年使用していました。これはうまく機能したと思います。5年以上定期的に Git を使っているテストリーダーのグループが、ある文や用語を理解できないと感じるのであれば、ドキュメントをより明確にするために更新すべきだと主張しやすくなります。

この「ソフトウェアのユーザーに既存のドキュメントについてコメントしてもらい、彼らが見つけた問題を修正する」というパターンは非常にうまく機能したと感じており、将来的にも試してみたいと思っています。

man ページの変更

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

私にとって最も興味深かったのは git push と git pull の変更です。これらのページの導入部を更新するだけでなく、以下も作成しました：

これらの変更を行うことで、オープンソースのドキュメントを維持する作業がいかに大変であるかを改めて実感しました。明確かつ正確な文章を書くことは容易ではなく、時には妥協を余儀なくされました。例えば、「git push may fail if you haven’t set an upstream for the current branch, depending on what push.default is set to.」という文は少し曖昧ですが、「depending」の正確な意味は非常に複雑で、それを解明するのは大きなプロジェクトです。

Git への貢献プロセスについて

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

  • Git には Discord サーバーがあり、「my first contribution」チャンネルで貢献を始めるためのサポートが得られます。Discord の人々はとても歓迎的でした。
  • すべての貢献に GitGitGadget を使用しました。これにより、GitHub のプルリクエスト（使い慣れたワークフロー）を作成でき、GitGitGadget がその PR を Git 開発者が使用するシステム（パッチが添付されたメール）に変換してくれました。GitGitGadget は非常にうまく機能し、Git でパッチをメールで送信する方法を学ぶ必要がなくて本当に助かりました。
  • その他は通常のメールクライアント（Fastmail のウェブインターフェース）を使用してメールに返信し、メーリングリストの慣習に従ってテキストを80文字で折り返しました。

また、lore.kernel.org のメーリングリストアーカイブはナビゲートしにくいと感じたので、長いメーリングリストのスレッドを読みやすくするために 独自の git list viewer をハックして作成しました。

貢献プロセスを進めるにあたり、また変更のレビューにおいて、多くの人々が助けてくれました：Emily Shaffer、Johannes Schindelin（GitGitGadget の作者）、Patrick Steinhardt、Ben Knoble、Junio Hamano など、ありがとうございました。

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