Re: [PATCH] Documentation/git-fsck.txt: include fsck.* config variables

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 29, 2019, 21:32 UTC
Message-ID: <xmqq5znkv86m.fsf@gitster-ct.c.googlers.com>
In-Reply-To: <20190729201236.GF14943@sigill.intra.peff.net>

Jeff King <peff@peff.net> writes:

Show 23 quoted lines

> On Mon, Jul 29, 2019 at 08:48:28AM -0700, Junio C Hamano wrote:
>
>> > Before this include let's add:
>> >
>> >     The below documentation is the same as what’s found in
>> >     git-config(1):
>> 
>> I actually do not think we would want to do that.  I am all for the
>> kind of 'include' proposed by this patch, and we should strive to
>> make it easier for us to make sure the duplicated text are in sync.
>> 
>> But that would mean that the readers will have to see the "is the
>> same as the other one" over and over.  If our documentation set is
>> consistent, they should not have to.
>> 
>> I think we *must* make such a note in a total opposite case,
>> i.e. "here are the summary of the most often used options; for full
>> list, see git-config(1)".
>
> I disagree. _We_ know that the content is the same, because we are
> looking at the source that says "include". But as a user, how do I know
> when I get to one section or the other that it is something I have
> already read and can skip over?

I want to raise the user expectation so that they would expect from our documentation, unless we say "these are different", we would never say conflicting things in two places.

So,... I disagree.