Re: Apologia for bzr

[Eli Zaretskii]

> Date: Thu, 2 Jan 2014 13:34:32 -0500
> From: "Eric S. Raymond" <address@hidden>
> Cc: address@hidden, address@hidden
> 
> >                It works on Unix and on Windows alike, and does both
> > seamlessly.
> 
> Not any more.  One of the reported symptoms of decline is that Windows 
> support has fallen by the wayside.  I don't care about this, so I
> haven't checked myself.

Don't believe it.  I use bzr on Windows all the time.

> >                  The documentation, while it can use some serious
> > improvement, is nevertheless orders of magnitude more clear than git's
> > man pages, which seem to have been written by some math professor who
> > can produce rigorous formal papers, but doesn't have the slightest
> > idea how to write useful and efficient user documentation.
> 
> I think this is a bit unfair.  In my experience the git pages are
> terrible as tutorials, but pretty clear as references once you have an
> overall grasp of how things work.

They are impenetrable.  The very first words will get you in a "WTF?"
mode.  Just try to read the first sentences of any random man page
through a newbie's eyes.  No term is ever explained before used -- do
these guys even understand what it means to _explain_ things?  It's as
if you need to learn a whole new language.  Here, a typical example
from git-commit:

  DESCRIPTION 

  Stores the current contents of the index in a new commit along with
   a log message from the user describing the changes.

Huh?  "Contents of the index"?  I used to know what commit was, now I
don't.

> They could easily be far, *far* worse.

Yeah, but that's hardly a compliment.