Re: [PATCH] doc: Modify git-add doc to say "staging area"

From: Stefan Beller <sbeller@google.com>
Date: Dec 14, 2017, 18:24 UTC
Message-ID: <CAGZ79kZeMVLesunBzW5hhN-snL8fBXdjPgy=Tt8JCDmhDePDZA@mail.gmail.com>
In-Reply-To: <xmqq6099uqq9.fsf@gitster.mtv.corp.google.com>

On Thu, Dec 14, 2017 at 10:08 AM, Junio C Hamano <gitster@pobox.com> wrote:

Show 16 quoted lines

> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>
>> On Wed, Dec 13, 2017 at 6:46 AM, David A. Wheeler <dwheeler@dwheeler.com> wrote:
>>> On December 13, 2017 12:40:12 AM EST, Jacob Keller <jacob.keller@gmail.com> wrote:
>>>>I know we've used various terms for this concept across a lot of the
>>>>documentation. However, I was under the impression that we most
>>>>explicitly used "index" rather than "staging area".
>>>
>>> I think "staging area" is the better term. It focuses on its purpose, and it is also less confusing ("index" and "cache" have other meanings in many of the repos managed by git).
>>
>> After your patch the majority of the docs will still talk about
>> "index", is this part of some larger series, perhaps it would be good
>> to see it all at once...
>
> ... or none of it.  I do not quite see a point of spending list
> bandwidth on a change like this one.

I think wording (as well as its consistency) in the documentation is rather important.

Just the other day I was reading[1], yet another blog explaining
why git sucks. TL;DR:
(1) (a) The staging area is an advanced concept
    and should be disabled by default
    (b) and is documented super confusingly.
(2) Branches and Remotes Management is
    Complex and Time-Consuming
(3) its ecosystem (GitHub et al.) is not pushing for
    innovation, because "forks are not the right model".

[1] https://gregoryszorc.com/blog/2017/12/11/high-level-problems-with-git-and-how-to-fix-them/

When I saw the original patch, I assumed it was a reaction to this blog and attempting to fix (1b), but maybe it is unrelated.

Anyway I think spending list band width on good documentation is not bandwidth wasted.

Stefan