Peter Shenkin <shenkin@xxxxxxxxx> writes: > 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? -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html