Re: Officially start moving to the term 'staging area'

From: Drew Northup <n1xim.email@gmail.com>
Date: Sep 4, 2013, 04:23 UTC
Message-ID: <CAM9Z-nmLQUrJk73pi_0a1_ccGMnqU_t=uOZze622_GEtWfMvQQ@mail.gmail.com>
In-Reply-To: <b677f1ae-662f-4728-b625-189bc392c74d@email.android.com>

On Fri, Aug 30, 2013 at 1:16 AM, Piotr Krukowiecki <piotr.krukowiecki@gmail.com> wrote:

Show 10 quoted lines

> Drew Northup <n1xim.email@gmail.com> napisał:
>>I agree with Junio. This effort is better spent making the
>>documentation clearer and more succinct. The reality is that a user
>>needs to build a model in their mind of what they are doing which maps
>>enough (completely is not required) to what is actually going on to
>>get work done. If the documentation or the instruction is getting in
>>the way of that in the name of simplifying the presentation then the
>>presentation is wrong.
>
> Why do you think the "stage"  model do not map enough?

When I try to explain how to use git to complete VCS newbies in general they find the "snapshot" model more mentally sensible than the "staging area" model. (In other words, the user doesn't care how, if, or where the program is maintaining state.) The "snapshot" model does not require knowledge of the index and does not get in the way of later on learning more advanced concepts which benefit from the index being explained as what it is--explanations which quite frequently bring up the "staging area" model (but in that case as a portion of the index used to store snapshot state information).

Show 12 quoted lines

>>We add content snapshots to the index of content (creating
>>"temporary"--they will be garbage collected eventually if they become
>>orphans--objects into the store at the same time). We build commits
>>from those snapshots (in whole or in part, typically only using the
>>most recent snapshots of new things added to the index) and save those
>>in the object store with the content and tree objects. Sometimes we
>>create tag objects to record something special about commits, trees,
>>and content blobs.
>
> The above can be rewritten to use the 'staging area' concept just
> fine. And I don't think you should say to inexperienced users things
> like 'tree objects'.

At what time did I say specifically what I tell newbies? I did not do so. Please refrain from making that sort of assumption. In any case, no, you cannot rewrite that to use "staging area" in place of "index" without introducing a different mental model and new concept into the text (a model which happens to be incomplete, but not incorrect). That minimalist summary was written for the technically-minded people here on this list debating the issue of communications with the users--the bane of all programmers' lives.

> A good exercise would be to take documentation of some command
> and show that it can or can't be rewritten to use the other term.

That may be a good exercise in matters of philosophy, but you will find few outside of the world of programming who would agree with that characterization of the optimization of technical writing. (In the English language in particular it is folly due to the extreme variation of available terms and metaphors with nearly identical denotations and greatly varying connotations.)

> Instead of 'indexing' or 'staging' content you could also use term 'mark'.
> You mark content to add, for removal, you can diff it or revert.

So far as I am concerned the introduction of a specific "staging area" (as if it has a distinct physical presence) is superfluous to that.

>>That's the real model (with some rough edges). Explaining what that
>>has to do with distributed version control is the hard part.

Again, let us keep our argument focused on communications with users. Renaming core objects is just going to sow confusion without fixing the user communication issue. That's what I meant the first time I wrote what I quote directly above and I'm sticking to it.

-- 
-Drew Northup
--------------------------------------------------------------
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59