Overview

Documentation is the gateway to any open-source project, yet it often lags behind the code. This guide walks you through a proven method for enhancing official documentation, using the Git project as a real-world example. You’ll learn how to identify gaps, conduct user research, and get your improvements accepted—even if you’re not a core maintainer. The principles apply to any project, but we’ll focus on the specific changes that made Git’s documentation clearer: introducing a data model and rewriting core man pages. By the end, you’ll have a repeatable workflow for turning documentation pain points into accepted patches.

Prerequisites

• Familiarity with Git basics (commit, branch, remote).
• A willingness to read and write technical English.
• Access to a Linux/Unix environment (or Windows with Git Bash) to test the documentation locally.
• A GitHub account to fork the Git source repository.
• Basic knowledge of AsciiDoc (the markup language used by Git documentation).

Step-by-Step Instructions

1. Identify Documentation Gaps

Start by reading the existing docs like a confused beginner. In Git’s case, terms like “object”, “reference”, and “index” were used everywhere but never explained together. The team noticed that a cohesive “data model” document was missing. To find gaps for your project:

• List concepts that are referenced in multiple places but never defined.
• Look for “we assume you know” phrases—those often hide missing explanations.
• Check issue trackers for repeated questions about the same topic.

For Git, the missing piece was a concise overview of how commits, trees, blobs, tags, and branches relate. Write down the mental model you wish you’d had.

2. Research and Understand the Internals

Before you explain, you must know the truth. Dive into the source code, existing documentation, and trusted third-party articles. For Git’s data model, the author studied how merge conflicts are stored in the staging area—something that surprised even experienced users. Here’s how to verify your understanding:

1. Experiment with Git commands – Use git cat-file -p to inspect objects, git ls-files --stage to see the index, and git show-ref for references.
2. Read the source – Look at Documentation/technical/ in the Git repo for existing technical notes.
3. Ask maintainers – If something is unclear, email the Git mailing list. They appreciate careful questions.

Example command to explore a commit object:

git cat-file -p HEAD

This shows the tree, parent, author, and message—the building blocks of Git’s data model.

3. Draft a Proposal Document

Write a short, accurate document (around 1600 words for Git’s data model) that explains the core concepts and how they connect. Use your project’s documentation markup (AsciiDoc for Git, RST for Python, etc.). Important tips:

• Define terms early – “An object is any of four types: blob, tree, commit, or tag.”
• Show relationships – Use diagrams or bullet points: “A branch is a moving pointer to a commit.”
• Include examples – “When you run git add, Git creates a blob and updates the index.”

For inspiration, check the Git Data Model that was eventually merged.

4. Recruit Test Readers

Expert bias is real. The Git docs team used social media (Mastodon) to gather non-expert readers. Here’s how to replicate that:

1. Post a clear ask – “Help me improve Git’s documentation! Read this page and tell me what confuses you.”
2. Target diverse audiences – Share in relevant forums, Reddit communities, and developer mailing lists.
3. Collect feedback systematically – Use a spreadsheet to track comments. The original effort received about 80 replies.

Example feedback questions:

• “What does ‘upstream’ mean in this context?”
• “Which sentence made you stop reading?”
• “What would you add or remove?”

5. Analyze and Iterate

Group feedback into patterns—terminology confusion, missing examples, unclear flow. In Git’s case, users didn’t understand “pathspec” or “reference”, and they wanted more concrete scenarios. Revise your draft accordingly. Then repeat the test (with a new set of readers if possible) until confusion is minimal.

Use version control for your draft too! Commit changes with messages like “Clarify definition of index based on reader feedback.”

6. Submit the Patch

Once your document is polished, fork the repository, create a branch, and send a patch or pull request. For Git specifically, patches go to the mailing list via git format-patch and git send-email. In other projects, a PR on GitHub is fine. In your submission:

• Reference the testing – Mention that 80 test readers reviewed it, which shows evidence-based improvement.
• Be ready for review – Maintainers will ask tough questions. For example, they challenged how merge conflicts appear in the index. Be prepared to defend or adjust.

Example patch subject line:
[PATCH] Documentation: add a data model overview

Common Mistakes

Assuming Your Perspective Is Right

Don’t argue from authority. Two experts debating “X is clearer” is unproductive. Instead, rely on data from test readers. The Git team learned that even “obvious” terms like “reference” needed explicit definition.

Overlooking Staging Area Details

Git’s index (staging area) is tricky. The original proposal initially got merge conflict storage wrong. Always double-check with commands like git ls-files --stage to see the exact structure.

Writing for Experts

Your audience is not yourself. Avoid jargon without explanation, and provide incremental learning paths. A common error is to describe “objects” without first explaining that a commit is an object that points to a tree.

Ignoring the Maintainers’ Workflow

Projects like Git have strict submission processes. Failing to follow them (e.g., sending an HTML file instead of AsciiDoc, or not signing off) will delay acceptance. Read Documentation/SubmittingPatches in the Git repo.

Summary

Improving open source documentation requires a blend of technical accuracy and user empathy. By finding gaps, testing with real readers, and iterating based on evidence, you can produce clear, maintainer-approved docs. The Git data model project succeeded because it replaced expert guesses with user data. Use this guide’s steps—identify, research, draft, test, iterate, submit—to contribute to any project. Your patch might be the one that finally explains “upstream” to a beginner.