Re: [PATCH v2 3/4] doc: git-add: make explanation less dry

From: Julia Evans <julia@jvns.ca>
Date: Aug 15, 2025, 16:10 UTC
Message-ID: <886787d2-26b5-4451-a105-9ab522e38ad6@app.fastmail.com>
In-Reply-To: <xmqq349ty254.fsf@gitster.g>

Hi,

> I somehow find the text before this change easier to understand
> (except for one thing).  "If you edit `file.c` after adding it" in
> the new text says the same thing as "if you want subsequent ... in
> the next commit" in the original but in a much better way.

I really appreciate all of this feedback. It makes me wonder if there would be a better way to approach this man page. Usually when I'm revising a technical explanation, I find people who are currently users of the software but who have trouble understanding how it works. Then I ask them to give feedback on what's confusing to them about the explanation or what questions they have.

I do this because I find that often people who are extremely comfortable with using the software (including me, which is why I usually spend so much time collecting feedback like this!) can lose sight of what's confusing to an "average user". And every time I'm part of a discussion about documentation for an open source project it seems a bit strange to me for a group of people who all already understand the concept to be discussing what would be clearest to an "average user": surely the users themselves should be the judge of what's clear to them!

I'm still pretty new to writing open source documentation so I don't know if collecting user feedback like this is a normal part of the process, but I always learn a lot from this type of feedback and it's pretty easy for me to collect it.

> Rewrite "diff --staged" to "diff --cached"

Will use `diff --cached`.

> In addition, we also should talk about
> "diff" to inspect what the user will be leaving out---in other
> words, what the user might have forgotten to add, which is equally
> if not more useful sanity-check you can do before you commit.

That makes sense to me.

best, Julia