Git Data Model Documentation in Practice: An Open-Source Documentation Improvement Method Based on User Feedback

Background: Why Git Documentation Needs Improvement

Julia Evans (well-known tech blogger) decided last fall to spend time improving Git's official documentation. Her motivation was straightforward: Git documentation heavily uses terms like "object," "reference," and "index" without clearly explaining these concepts or describing their relationships to core concepts like "commit" and "branch."

To understand the root of this problem, you need to understand the nature of Git's data model: Git is a content-addressable storage system based on a Directed Acyclic Graph (DAG). "Content-addressable" means that each object's unique identifier (hash value) is determined by its content itself, not by its storage location—this means identical file contents are stored only once throughout the entire repository history, naturally achieving deduplication. The DAG structure ensures the immutability of commit history: each commit object contains the hash value of its parent commit, so any modification to history causes a cascading change in all subsequent commit hashes, making tampering immediately detectable. The core object types include blob (stores file content), tree (stores directory structure), commit (stores commit information and a pointer to a tree), and tag (stores tag information), with each object uniquely identified by a SHA-1 or SHA-256 hash value. "References" are human-readable names pointing to these objects—a branch is essentially a mutable reference pointing to a specific commit object, while HEAD is a special reference pointing to the current branch. The concepts in this data model are interdependent; any unexplained term creates a gap in understanding.

This isn't a minor issue. For developers who have used Git for years, understanding how Git organizes its commits and branch data is key to truly grasping how Git works. So Julia and Marie wrote a completely new "data model" document for Git.

Git Data Model Documentation: Core Architecture in 1600 Words

This data model document is now available in the Git repository and is expected to appear on the official Git website after the next release. Worth noting is that Git's documentation is written in AsciiDoc format (with the .adoc file extension), then converted through a toolchain into terminal-readable man page format or web HTML format.

The man page format, originating from the 1971 Unix system, has deep historical roots: it was born in an era when computer storage was extremely expensive, so documentation had to be extremely concise to save disk space, establishing a tradition of "reference manual" rather than "teaching material." The standard man page structure (NAME, SYNOPSIS, DESCRIPTION, OPTIONS, and other fixed sections) was designed for quick lookup, not for beginner comprehension. This format naturally favors a concise reference style over instructional narrative, structurally constraining the depth of terminology explanations. This explains why even experienced developers often feel confused when facing Git man pages—the documentation format itself assumes readers already possess considerable background knowledge.

The document's core goal is to accurately describe Git's data model in a brief format (only 1600 words). However, "accuracy" isn't easy—even though Julia already understood the basic principles of Git's data model, during code review she still learned many new details, such as how merge conflicts are stored in the staging area, and made extensive revisions accordingly.

It's worth explaining the staging area's underlying mechanism in more depth: Git's index (staging area) is not simply a "list of files to be committed" but rather a binary file (.git/index) that stores file paths, permissions, timestamps, and corresponding blob hashes. When a merge conflict occurs, the index enters a special state—for conflicted files, the index simultaneously holds three version entries: stage 1 (common ancestor version), stage 2 (current branch version), and stage 3 (merged branch version). This is the underlying reason why the git checkout --ours/--theirs command works, and it's a detail that even experienced Git users may never have deeply explored. Understanding this mechanism also explains why git status displays "both modified" during conflict states, and why you must execute git add after resolving conflicts to mark them as resolved—essentially merging the three-way entries in the index back into a single entry.

This experience illustrates an important fact: even experienced Git users may have blind spots in their understanding of underlying mechanisms. Official documentation is the ideal place to fill these gaps.

Evidence-Based Documentation Improvement Methods

Debates Between Experts Are Often Ineffective

While improving the man pages for core commands like git push and git pull, Julia quickly realized that "improving based on one's own best judgment" doesn't work. A common problem in open-source documentation discussions is: two expert users arguing over which explanation is clearer ("I think X's wording is better!" "No, Y is better!").

She points out that such debates are usually unproductive—expert users of software are notoriously unreliable at judging whether an explanation is clear to non-experts. There's a corresponding explanation in cognitive science: experts are often affected by the "Curse of Knowledge," finding it difficult to reconstruct the cognitive state of not understanding a concept, so their judgment of "what constitutes a clear explanation" systematically biases toward their existing knowledge framework.

The "Curse of Knowledge" concept was formally introduced by economists Colin Camerer and colleagues in their 1989 research, and has since been widely cited by psychologists and educators. Its core mechanism is: once we've mastered a piece of knowledge, we can hardly imagine "what it feels like not to know this," because existing knowledge automatically and unconsciously fills in our understanding process. In technical documentation, this bias is particularly prominent: senior engineers reviewing documentation tend to automatically fill in implicit premises that are completely opaque to newcomers, thereby misjudging the document's clarity. This is why many open-source project documents remain obscure to new users despite repeated review by core contributors—the reviewers' professional background itself constitutes a blind spot. The value of Julia's methodology lies precisely here: replacing internal intuition with external evidence to systematically circumvent the interference of the Curse of Knowledge.

Recruiting Real Users to Identify Documentation Problems

Julia adopted a more "evidence-based" approach: she recruited approximately 80 test readers on Mastodon, asking them to read existing documentation and report points of confusion. Most of these readers had 5-10+ years of Git experience.

Test readers provided extensive valuable feedback:

• Unfamiliar terms: What is a pathspec? What does "reference" mean? Does "upstream" have a specific meaning in Git?
• Specific confusing sentences
• Content suggestions: "I frequently do X operation, I think it should be included in the documentation"
• Inconsistencies: "This implies X is the default, but elsewhere implies Y is the default"

The elegance of this method lies in: if a group of test readers who have used Git for over 5 years find a sentence or term incomprehensible, it's easy to argue that the documentation needs updating. This method essentially borrows from the "usability testing" approach in User Experience Research (UX Research)—rather than relying on the designer's subjective judgment, it locates problems by observing real users' points of confusion. It's worth noting that Julia's chosen test group (5-10 years of Git experience) was itself carefully considered: these users are familiar enough with everyday Git usage to identify technical errors in documentation, while not being so immersed (like core developers) that all terms seem self-evident, thus representing the reader demographic the documentation most needs to serve.

Specific Documentation Improvement Results

Four core Git command man pages were ultimately updated:

• git add
• git checkout
• git push
• git pull

The changes to git push and git pull were the most interesting. Besides updating the introduction sections, new additions included:

• A dedicated section describing what "upstream branch" means (which had never been properly explained before)
• A clear description of "push refspec"

"Upstream branch" is a term that has long lacked a clear official definition in Git, and its meaning differs across contexts. For local branches, the upstream branch is the tracking relationship set through git branch --set-upstream-to or git push -u, typically pointing to the corresponding branch in a remote repository (e.g., origin/main). The underlying implementation of this tracking relationship is stored in the .git/config file, recorded as branch.<name>.remote and branch.<name>.merge configuration entries. This tracking relationship determines where git pull fetches from by default, where git push pushes to by default, and the baseline for the "ahead/behind" information displayed by git status—the latter is actually calculated by computing the commit difference between the local branch and the remote tracking branch using git rev-list. In the open-source community context, "upstream" also commonly refers to the original project repository (relative to a fork), such as when you fork a project and add the original repository as a remote locally, it's conventionally named "upstream." This polysemy is precisely the source of ambiguity that had never been directly addressed in documentation, and the fundamental cause of confusion for many developers in collaborative scenarios.

Practical Compromises in Documentation Maintenance

This experience gave Julia a deep appreciation for the workload of maintaining open-source documentation. Writing content that is both clear and accurate isn't easy, and sometimes compromises must be made. For example, this sentence:

"git push may fail if you haven't set an upstream for the current branch, depending on what push.default is set to."

The exact meaning of "depending" here is very complex—push.default has five possible values: nothing, current, upstream, simple, and matching, each with different behavior in different scenarios—fully expanding the explanation would be an enormous undertaking, so they chose to maintain moderate ambiguity. This "intentional incompleteness" is actually an important professional judgment in technical writing: the goal of documentation is to reduce the reader's cognitive load, not to pursue encyclopedic completeness. Overly detailed explanations can sometimes drown out core information, causing readers to lose their way in a sea of details. Finding the balance between accuracy and readability is a core skill that technical writers need to continuously hone.

How to Contribute Documentation to Git

For developers who want to contribute documentation to Git, Julia shared some practical information:

1. Git has a Discord server with a "my first contribution" channel