こんにちは、BFS(Byte Freaks Studio)です。 🎲
今日は、ジュリア・エヴァンスが昨年1月に自身のブログに投稿した記事をご紹介したいと思います。それは、Gitの公式ドキュメント（documentation）を自ら修正した話です。
Gitを使っていると、一度はobject、reference、indexといった用語の前で立ち止まったことがあるはずです。ジュリアも同じところで立ち止まり、結局同僚のMarieと一緒にGitの公式マニュアルページ（man page）のいくつかを直接修正することにしました。
80人のテスト読者から「どこが分かりにくいか」というフィードバックを受けながら、git add、git checkout、git push、git pullのページをブラッシュアップした過程、そしてその中で知ることになったオープンソースのドキュメント作成作業における意外な難しさまで、Gitユーザーなら興味深く読んでいただける内容です。
翻訳は以下に続きます。原文が気になる方はこちらから直接ご確認いただけます。
楽しんで読んでください。 🎲
Gitのデータモデル（およびいくつかのドキュメントの更新）
こんにちは！
去年の秋、私はGitのドキュメントを改善する作業に時間を充ててみることにしました。普段、ドキュメントが物足りないと感じたときは、ブログ記事やZine（小冊子）を別途書くことで解決してきました。しかし、今回はふとこんな考えが浮かびました。
"公式ドキュメント自体をもっと良くすることはできないだろうか？"
そこで、同僚のMarieと一緒に、Gitドキュメントにいくつかの改善作業を行いました。
Gitのためのデータモデル
Gitのドキュメントを調べてみると、Gitはobject、reference、indexといった用語を非常に頻繁に使用していました。しかし、これらの用語が正確に何を意味するのか、そしてcommitやbranchといった核となる概念とどのような関係があるのかを説明する資料が不足していることに気づきました。
そこで、私たちは新しい"データモデル(Data Model)"ドキュメントを作成しました。
現在はこちらで読むことができ、次回のリリース以降にはGit公式ウェブサイトにも含まれる予定です。
BFS NOTE: 現在はGit公式ウェブサイトに反映されています。
私がこの作業に特に満足している理由は、Gitがコミットやブランチのデータをどのように構成しているかを理解することが、長年Gitを理解する上で大きな助けになってきたからです。そのため、Gitのデータモデルを短く（約1,600単語）、かつ正確に説明する文書がどうしても必要だと考えていました。
ただ、正確であるということは思ったより簡単ではありませんでした。基本的な構造はすでに知っていましたが、レビューの過程で多くの新しい詳細事項を学ぶことになり、それに伴い多くの部分を修正しなければなりませんでした。例えば、マージコンフリクト（merge conflict）がステージングエリアにどのように保存されるかについての説明も修正されました。
git push、git pullなどを含むドキュメントの改善
また、Gitの主要なマニュアルページ（man page）数件の導入部を改善する作業も進めました。
最初は単に「自分がより良いと思う方向に直してみよう」と考えましたが、すぐに問題があることに気づきました。
"自分の説明の方が良いと言ったところで、Gitのメンテナーたちがそれを信じてくれる理由があるだろうか？"
オープンソースのドキュメント作業をしていると、このような状況をよく目にします。
"このように説明するほうがより明確ではないだろうか？"
"いや、あのように説明するほうがもっと良いのでは？"
しかし、ソフトウェアの専門家同士で「どちらの説明がより理解しやすいか」を論争することは、それほど生産的ではないと考えました。特定のツールを長く使っている人は、初心者が何に苦労しているのかを判断するのが難しい場合が多いからです。
そこで、私たちはもう少し根拠に基づいた方法を見つけたいと考えました。
テスト読者を通じて問題を見つける
Mastodonでボランティアを募り、既存のドキュメントを読んでみて、どこが分かりにくいか、どのような疑問が生じるかを教えてほしいと依頼しました。
約80名のテスト読者が意見を寄せてくださり、その過程で本当に多くのことを学びました。
人々が残してくれたフィードバックは非常に多様でした。
理解しにくい用語
pathspecとは何ですか？?referenceはどういう意味ですか？ mean?upstreamという用語は、Gitにおいて特別な意味がありますか？ có ý nghĩa đặc biệt gì trong Git không? have a special meaning in Git?
特定の文章が理解しにくいという意見
追加してほしい内容の提案
「私はいつもこのような作業をしているので、ここに含まれると嬉しいです。」
ドキュメント間の不一致の指摘
ある場所ではXがデフォルトであるかのように見えますが、別の場所ではYがデフォルトであるかのように見えます。
興味深かった点は、テスト読者のほとんどがGitを少なくとも5〜10年以上使用している人たちだったということです。
これがむしろ良かったです。Gitを長年使ってきた人々でさえ、ある文章や用語を理解しにくいと感じるのであれば、それはドキュメントをより明確に修正すべきだという強力な根拠になるからです。
このような方式、つまり
"実際のユーザーが既存のドキュメントを読んで問題点を指摘すれば、その問題を修正する"
というアプローチが非常に効果的だと感じましたし、今後も他のプロジェクトで再び試してみたいと思っています。
どのマニュアルページを修正しましたか？
私たちは次の4つのマニュアルページを修正しました。
特にgit pushとgit pullの作業が最も興味深かったです。
導入部を改善するだけでなく、次の内容を新しく作成しました。
upstream branchとは何かを説明するセクション(以前は事実上、まともに説明されていませんでした。)
push refspecに関する説明の整理explanation cleanup
この作業をしながら、オープンソースのドキュメントをメンテナンスすることがいかに難しいか、改めて実感しました。
"文章は明快であるだけでなく、同時に事実とも一致していなければなりません。"
時には妥協も必要でした。例えば、次の文章を見てみましょう。
git pushmay fail if you haven't set anupstreamfor the current branch, depending on whatpush.defaultis set to.
("現在のブランチのupstreamが設定されていない場合、push.defaultの設定によってはgit pushが失敗することがあります。")
この説明は多少曖昧です。しかし、「設定によって」が正確に何を意味するのかを完全に説明するには、はるかに複雑な内容を扱う必要があり、それだけで一つの大きなプロジェクトになるほどでした。
Gitへの寄稿プロセスについて
Gitの開発プロセスを理解するのにも、かなりの時間がかかりました。
ここで全てを説明するつもりはありません。それだけで別の記事が一編書けてしまうほどですから。
代わりに、いくつか短いメモを残しておきます。
GitにはDiscordサーバーがあり、初めて貢献する人のための"my first contribution"チャンネルがあります。
始めるのに必要な助けを得ることができましたし、皆とても親切でした。
私はすべての貢献をGitGitGadgetを通じて行いました。
GitHub Pull Requestという慣れ親しんだワークフローを使用することができ、
GitGitGadgetがこれをGit開発者たちが使用するメールパッチ形式に変換してくれました。
おかげで、メールパッチを送る方法を新たに学ぶ必要がありませんでした。
レビューに返信する際は、普段使っているメールクライアント（Fastmailのウェブインターフェース）を使用しました。
メーリングリストの慣習に合わせて、テキストを80文字単位で改行しました。
また、lore.kernel.orgのメーリングリストアーカイブは、探索するのが多少不便でした。そのため、長い議論のスレッドを読みやすくするために、個人的に簡単なGitメーリングリストビューアを作成して使用しました。
貢献の過程やレビューの過程では、多くの方々の助けを借りました。Emily Shaffer、Johannes Schindelin（GitGitGadgetの作成者）、Patrick Steinhardt、Ben Knoble、Junio Hamanoをはじめとする多くの方々に感謝いたします。
BFS
この文章で最も印象的だった部分は、ジュリアが「自分の方がうまく説明できる」という確信だけで文書を直さなかった点でした。代わりに、実際のユーザーの反応をまず集め、そのデータを根拠に修正の方向性を決めました。2人の専門家が「この表現の方が明確だ」と論争するよりも、実際に混乱している人々の声を聞く方が、はるかに信頼できるということです。
Gitを毎日使っていながらも、どこか腑に落ちなかった表現があったなら、この記事がその答えを少しは示してくれるかもしれません。
これからは、ジュリアがこれまで自身のブログに綴ってきたGitに関する記事を一つずつ選んで、翻訳して紹介していこうと思います。ある記事は私たちがGitを使いながらよく経験する些細な不便さを、またある記事は慣れ親しんでいると思っていた概念に対する誤解を改めて見つめ直すような内容です。
『How Git Works』とあわせて読むと理解がより一層深まるような記事を、一つずつゆっくりお届けする予定ですので、楽しみにしていてください。 🎲
- BFS 🎲