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

I've returned with some data! I got feedback on the `git-add` man page from 13 Git users. It's a group of pretty experienced users: half of them have been using Git for 5-10 years, and about half for 10+ years. Even though there are no "novices" here, they still provided useful feedback about what's confusing.

Here's what I took away from the feedback and a summary of the comments. First, what I took away:

* The term "index" is hard to understand even for very experienced Git users,
  and even for some users who say that they are extremely comfortable with Git.
* The second sentence in the man page is too long and hard to parse.
* The "(quote your globs before the shell)" phrasing is confusing.
* I thought mentioning that you can use `git reset` to undo a `git add` was a
  good idea.
* Leaving something similar to the existing phrasing around "snapshot" seems
  fine, nobody in this group was confused, though of course this is a group
  of people who already understand how `git add` works.

Here's my summary of the comments on the existing man page. I collected them using this little tool I built: https://text-feedback.wizardzines.com/git-add/. I'm happy to also figure out how to best share the "raw" comments if folks would find that helpful. I've quoted the current man page text for context.

This was the paragraph with the most "this is confusing" comments. Here are the main themes:

1. 7 people (more than half) said that they find the term "index" confusing. A
   few example quotes:
   * "updates the index" sounds like it increments something"
   * "Is the index not just the content that is staged for commit? Do I as an
	 end user need to care about the difference? I've not heard the staged
	 content referred to as the index before, even in git command outputs."
2. 3 people said the second sentence is too long and hard to parse
3. 2 people said that "It *typically* adds the current content of existing
   paths" is confusing (What's meant by "typically"? When does it not do that?
   is this referring to git add -A?)

Nobody said they were confused by this, other than continued confusion around the term "index", like:

* "Why quotes around "index" here but not when I first encounter the word
  index?"
* "I'm guessing index is used through git man pages and staging area is a newer
  way of saying this 🤔"
* "Can we just say staging area? I don't think of adding changes to the "index""

Comments not related to the term "index":

* "Would prefer something more direct like "git lets you gradually build the
  contents of the next commit by adding things to the staging area...""
* "I wish this came first in the description."
* One person said they appreciated "you must use the add command [after making
  any changes]", since that confused them when they started using git

No comments other than "Can be improved to be more clear."

4 people did not understand what "(quote your globs before the shell)" meant. ("Does it mean that I need to escape glob quotation marks?").

Nobody said they were confused by this. One person said they were happy it was mentioned, and one person suggested replacing "obtain" with "get".

Things people said they learned from the man page:

1. "I did not know that the globs would be treated potentially differently if
   expanded by the shell before getting to git."
2. "I never knew git could do globbing."
3. "I didn't know you could remove paths with add"

Things people suggested adding:

1. "This should also document how to undo the effects of "git add". I'm always
   confused between how best to do so between "git restore" and "git reset"."