user guide help (definitions of terms)

[Martin Pool]

2009/8/7 John Yates <jyates at netezza.com>:

> It is clear that bzr CAN make terms mean whatever it chooses.  Actually
> doing so is unlikely to result in 'newbie delight'.

Saying this is much easier than finding terms which actually do make
sense to new users.

If you use words, like say branch, that people may have heard before,
they will have diverse reactions and expectations because they've
heard it in cvs or clearcase or perforce or git.  On the other hand if
you use a word that's previously unbound, like say 'loom', you can be
criticized for using quirky or unfamiliar terms.

We are introducing new concepts.  There are no existing words that
mean precisely the right thing.

I think having words that are both verbs and nouns is OK as long as
the meanings are consistent, as they are with say "code" or "download"
or "file".

> As evidenced in this very thread the term "working tree" is poorly
> chosen.  Naïve users will almost surely identify the contents of the
> tree within which they are working as their "working tree".

That's great, that's what it is.

> How does
> a newbie come to understand that the "working tree" is the "map" and
> not the "territory"?

??

> Figuring out the semantics of add versus remove and whether they are
> inverses has proven difficult.  Perhaps the issue could be clarified
> by introducing the concepts of "versioning" and "unversioning".

We do have the concept of versioned and unversioned files.

-- 
Martin <http://launchpad.net/~mbp/>