Re: Apologia for bzr

[Toby Cubitt]

On Thu, Jan 02, 2014 at 10:44:03PM +0200, Eli Zaretskii wrote:
> > >                  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.

This is the Emacs mailing list I'm on, right? Emacs of "find" a file to
open it, files live in "buffers", "windows" aren't windows but "frames"
are, "kill" to cut and "yank" to paste fame? ;-)

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

The same could be said of most unix man pages. Good man pages aren't
supposed to be tutorials. They're supposed to be reference manuals, for
looking up a terse and comprehensive description of usage, options,
switches, flags etc. Or at least, that's how I've always understood (and
used) them.

And there *are* decent git tutorials available from the official web site
that explain things without assuming you already know how git works
(e.g. http://git-scm.com/book isn't bad).

I'm not a great fan of the git UI. But complaining that the git man pages
are precisely what man pages are supposed to be is a little disingenuous.

Or maybe my problem is I'm a maths professor :)

Toby
-- 
Dr T. S. Cubitt
Royal Society University Research Fellow
and Fellow of Churchill College, Cambridge
Centre for Quantum Information
DAMTP, University of Cambridge

email: address@hidden
web:   www.dr-qubit.org