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

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 15, 2025, 19:47 UTC
Message-ID: <xmqqsehspdtr.fsf@gitster.g>
In-Reply-To: <886787d2-26b5-4451-a105-9ab522e38ad6@app.fastmail.com>

"Julia Evans" <julia@jvns.ca> writes:

Show 7 quoted lines

> ... 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".

Yes, you can lose your novice status and it is hard to take it back ;-) I agree with you that the next best thing you can do is to see how well folks who still have that status do.

Show 5 quoted lines

> 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!

Yes, with one caveat, which is that you need to be careful to avoid throwing them into local optima. A simplified world view may make it look easier to swallow, but depending on the kind of white lies you throw at them, some of them they may have to unlearn to further understand the system.