Re: [PATCH] Clarify that '--tags' fetches tags only

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 30, 2011, 18:37 UTC
Message-ID: <7vwrcpoozk.fsf@alter.siamese.dyndns.org>
In-Reply-To: <loom.20110930T041939-332@post.gmane.org>

Peter Shenkin <shenkin@gmail.com> writes:

Show 6 quoted lines

> Perhaps it will be useful to say what would have been most
> helpful for me. In the current documentation for "fetch
> --tags", one sentence reads, "This flag lets all tags and
> their associated  objects be downloaded." The following small
> modification would, IMO, be sufficient: "This flag causes all
> tags and their associated objects (only) to be downloaded."

Hmm, from time to time we seem to see this kind of documentation suggestion where:

 - We (try to) describe what xyzzy does by saying "This is what xyzzy
   does". We specifically do not say "In addition to what normally
   happens, xyzzy causes these additional things to happen."

 - The reader (somehow) assumes xyzzy does more than what we described in
   the documentation, even we did not say "In addition to..."; and then

 - A patch is proposed to add "these other things are _not_ done", after
   existing "This is what xyzzy does".

And it is not limited to the description of this particular option.

I think in general our documentation aims to spell out _all_ that happens, and explicitly say "In addition to what normally happens", "This page lists only the most common ways", etc., when such a clatification is needed.

I am wondering if there is a systemic failure that gives an impression that by default the documentation is incomplete and all other unspecified thing also happens to the readers? If so are there things that we could do better without going through individual description?