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

[Junio C Hamano <gitster@pobox.com>]

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

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

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