user guide help (definitions of terms)

[John Yates]

On Thursday, August 06, 2009 at 1:51 AM Russel Winder wrote:

> Yes it does.  When associated with DVCS, branch has at least two
> definitions as a noun and two definitions as a verb :-(

If bzr truly aspires to introduce the unwashed masses to dVCS huing
to confusing terminology because it is familiar to bzr's developers
and current users will be counter productive.  Along with clarifying
the UI in the 2.0 -> 3.0 era it might be worth considering introducing
a truly well thought out, unambiguous terminology without confusing
connotations.  Otherwise, to the uninitiated bzr risks coming off as
Humpty Dumpty:

  'When _I_ use a word,' Humpty Dumpty said in rather a scornful tone,
  'it means just what I choose it to mean -- neither more nor less.' 

  'The question is,' said Alice, 'whether you CAN make words mean so
  many different things.' 

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

Some random thoughts:

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".  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".

/john