Hello, this is BFS (Byte Freaks Studio). ๐ฒ
Today, I would like to introduce a post that Julia Evans wrote on her blog last January. It is the story of how she personally contributed to fixing the official Git documentation.
If you've used Git, you've likely hesitated at least once when encountering terms like object, reference, and index. Julia got stuck at the same point, and eventually, she and her colleague Marie set out to personally improve several of Git's official manual pages (man pages).
This is a story that any Git user will find interesting, covering the process of refining the git add, git checkout, git push, and git pull pages based on feedback from 80 test readers about "what was confusing," as well as the unexpected difficulties of open-source documentation discovered along the way.
The translation follows below. If you are curious about the original text, you can check it directly here.
Please enjoy the read. ๐ฒ
Git's Data Model (and some documentation updates)
Hello!
Last fall, I decided to spend some time improving the Git documentation. Usually, when I felt the documentation was lacking, I would address it by writing a separate blog post or a zine. But this time, a thought occurred to me.
"Could I make the official documentation itself a little better?"
So, together with my colleague Marie, I worked on several improvements to the Git documentation.
Data model for Git
While looking through the Git documentation, I noticed that Git frequently uses terms like object, reference, and index. However, I found a lack of resources explaining exactly what these terms mean and how they relate to core concepts like commit or branch.
So we have written a new "Data Model" document.
You can read it here now, and we expect it to be included on the official Git website after the next release.
BFS NOTE: It is currently reflected on the official Git website.
The reason I am particularly satisfied with this work is that understanding how Git organizes commit and branch data has long been a huge help in understanding Git itself. Therefore, I felt there was a strong need for a document that explains Git's data model accurately, even if it is brief (about 1,600 words).
However, being accurate was more difficult than I thought. Although I already knew the basic structure, I learned many new details during the review process and had to revise several parts accordingly. For example, the explanation of how merge conflicts are stored in the staging area was also corrected.
Improving documentation including git push, git pull, etc.
I also worked on improving the introductory sections of several major Git manual pages (man pages).
At first, I simply thought, "Let's fix it in the way I think is better," but I soon realized there was a problem.
"Even if I say my explanation is better, why would the Git maintainers have any reason to believe that?"
You often encounter this situation when working on open-source documentation.
"Wouldn't it be clearer to explain it this way?"
"No, wouldn't it be better to explain it that way?"
However, we felt that debating "which explanation is easier to understand" among software experts was not very productive. This is because people who have used a specific tool for a long time often find it difficult to judge what beginners struggle with.
So we wanted to find a more evidence-based method.
Finding problems through test readers
We recruited volunteers on Mastodon and asked them to read the existing documentation and let us know what was confusing or what questions they had.
About 80 test readers provided their feedback, and I learned a great deal in the process.
The feedback people left was very diverse.
Difficult terminology
What is
pathspec?What does
referencemean?Does the term
upstreamhave a special meaning in Git?
Feedback stating that a specific sentence is difficult to understand
Suggestions for content to be added
"I always do this kind of work, so I would like it to be included here."
Pointing out inconsistencies between documents
In one place, it looks like X is the default, but in another place, it looks like Y is the default.
What was interesting was that most of the test readers were people who had used Git for at least 5 to 10 years or more.
This was actually a good thing. If even people who have used Git for a long time find certain sentences or terms difficult to understand, it serves as strong evidence that the documentation needs to be revised more clearly.
This kind of approach, namely
"If an actual user reads the existing documentation and points out a problem, fix that problem"
I felt that this approach was very effective, and I plan to try it again in other projects in the future.
Which manual pages were modified?
We modified the following four manual pages.
The git push and git pull operations were particularly interesting.
In addition to improving the introduction, I have newly written the following content.
A section explaining what an
upstream branchis(Previously, it was practically not explained properly.)
push refspecexplanation cleanup
While doing this work, I realized once again how difficult it is to maintain open-source documentation.
"A sentence must not only be clear, but it must also be factually accurate at the same time."
Sometimes, compromise was necessary. For example, let's look at the following sentence.
git pushmay fail if you haven't set anupstreamfor the current branch, depending on whatpush.defaultis set to.
("git pushmay fail depending on thepush.defaultsetting if theupstreamfor the current branch is not set.")
This explanation is somewhat vague. However, explaining exactly what "depending on the setting" means would require covering much more complex content, which in itself was enough to become a major project.
About the process of contributing to Git
It also took quite a while to understand Git's development process.
I don't intend to explain everything here. That alone could be a separate post in itself.
Instead, I will leave a few short notes.
Git has a Discord server, and there is a "my first contribution" channel for first-time contributors.
I was able to get the help I needed to get started, and everyone was very kind.
I made all my contributions through GitGitGadget.
I was able to use the familiar workflow of a GitHub Pull Request,
GitGitGadget converted them into the email patch format used by Git developers.
Thanks to this, I didn't have to learn a new way to send email patches.
When responding to reviews, I used my usual email client (Fastmail web interface).
I wrapped the text at 80 characters to follow mailing list conventions.
Additionally, the mailing list archives on lore.kernel.org were somewhat inconvenient to navigate. Therefore, I personally created and used a simple Git mailing list viewer to make long discussion threads easier to read.
I received help from many people during the contribution and review process. I would like to thank Emily Shaffer, Johannes Schindelin (author of GitGitGadget), Patrick Steinhardt, Ben Knoble, Junio Hamano, and many others.
BFS
The most striking part of this article was that Julia didn't revise the documentation based solely on the conviction that "I can explain it better." Instead, she first gathered actual user feedback and determined the direction of the revisions based on that data. It shows that listening to the voices of people who are actually confused is far more reliable than two experts arguing over which expression is "clearer."
If there were expressions that felt somewhat unclear even while using Git every day, this post might provide some of the answers.
Moving forward, I plan to select and translate Julia's blog posts about Git one by one. Some posts address the minor inconveniences we often encounter while using Git, while others re-examine misunderstandings of concepts we thought we were familiar with.
These articles will deepen your understanding when read alongside ใHow Git Worksใ, so please look forward to them as I release them one by one. ๐ฒ
- BFS ๐ฒ