大家好！去年秋天，我决定花些时间完善 Git 的文档。我一直想参与开源文档的编写工作——通常情况下，如果我觉得某个东西的文档可以改进，我会写一篇博客文章、一本小册子之类的。但这次我想：我是否可以对官方文档做一些改进呢？
于是，我和玛丽对 Git 文档做了一些修改！
Git 的数据模型
在编写文档一段时间后，我们注意到 Git 的文档中频繁使用“对象”、“引用”或“索引”等术语，但并没有很好地解释这些术语的含义，也没有说明它们与其他核心概念（例如“提交”和“分支”）之间的关系。因此，我们编写了一份新的“数据模型”文档！
目前你可以在这里查看数据模型。我估计在某个时候（比如下一个版本发布之后？），它也会发布在Git 网站上。
我对此感到兴奋，因为了解 Git 如何组织其提交和分支数据确实帮助我理解了 Git 多年来的工作原理，我认为拥有一个简短（1600 字！）且准确的数据模型版本非常重要。
“准确”部分其实并不容易：我了解 Git 数据模型的基本工作原理，但在审查过程中，我了解到一些新的细节，不得不做出一些更改（例如合并冲突在暂存区中的存储方式）。
git push 、 git pull等的更新
我还参与了更新 Git 一些核心手册页的引言部分。我很快意识到，“仅凭我的最佳判断来改进它”是行不通的：维护者为什么要相信我的版本更好呢？
在讨论开源文档的修改时，我经常看到这样的问题：两位软件专家用户争论某个解释是否清晰（“我认为 X 是一个不错的解释方式！嗯，我认为 Y 会更好！”）。
我认为这种方法效率不高（众所周知，软件的专家用户很难判断一个解释对非专家是否清晰），所以我需要找到一种更有证据依据的方法来识别手册页的问题。
让测试读者找出问题
我在 Mastodon 上邀请了一些测试读者阅读当前版本的文档，并告诉我他们觉得哪些地方令人困惑或有什么疑问。大约有 80 位测试读者留下了评论，我从中受益匪浅！
人们留下了大量非常好的反馈，例如：
- 他们不理解的术语（什么是路径规范？“引用”是什么意思？“上游”在 Git 中有特定含义吗？）
- 具体令人困惑的句子
- 建议添加的内容（“我经常做X，我认为应该把它加在这里”）
- 前后矛盾之处（“这里暗示 X 是默认值，但在其他地方暗示 Y 是默认值”）
大多数测试读者都使用 Git 至少 5-10 年了，我认为这效果很好——如果一群使用 Git 超过 5 年的测试读者发现某个句子或术语无法理解，那么就很容易论证应该更新文档以使其更清晰。
我认为这种“让软件用户对现有文档发表评论，然后修复他们发现的问题”的模式效果非常好，我很期待将来有机会再次尝试。
手册页的变化
我们完成了这 4 个 man 手册的更新：
git push和git pull更改对我来说最有趣：除了更新这些页面的介绍之外，我们最终还编写了以下内容：
- 本节解释了“上游分支”一词的含义（之前并没有真正解释过）。
- 对“推送参考规范”的更清晰描述
做出这些更改让我真正体会到维护开源文档的工作量有多大：要写出既清晰又真实的内容并不容易，有时我们不得不做出妥协，例如“如果您没有为当前分支设置上游， git push可能会失败，具体取决于push.default的设置。”这句话有点含糊不清，但“取决于”的具体含义非常复杂，要理清这些细节是一个大工程。
关于向 Git 做贡献的过程
我花了一段时间才理解 Git 的开发流程。我不会在这里详细描述（这完全可以另写一篇文章！），只简单提几点：
- Git 有一个Discord 服务器，其中有一个“我的第一个贡献”频道，可以帮助你入门贡献代码。我发现 Discord 上的用户都非常友好。
- 我使用GitGitGadget来完成所有代码贡献。这意味着我可以提交 GitHub pull request（我很熟悉这种工作流程），而 GitGitGadget 会将我的 PR 转换成 Git 开发者使用的格式（以邮件附件的形式发送补丁）。GitGitGadget 非常好用，我非常感激它让我不必学习如何使用 Git 发送邮件补丁。
- 否则，我会使用我常用的电子邮件客户端（Fastmail 的网页界面）回复邮件，并将文本换行到每行 80 个字符，因为这是邮件列表的规范。
我还发现lore.kernel.org上的邮件列表存档很难浏览，所以我自己编写了一个 git 列表查看器，以便更容易阅读冗长的邮件列表讨论串。
很多人帮助我完成了贡献过程并审查了更改：感谢 Emily Shaffer、Johannes Schindelin（GitGitGadget 的作者）、Patrick Steinhardt、Ben Knoble、Junio Hamano 等等。