From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Toby Cubitt Newsgroups: gmane.emacs.devel Subject: Re: Apologia for bzr Date: Thu, 2 Jan 2014 21:14:52 +0000 Message-ID: <20140102211452.GA28685@c3po> References: <83sit6xgfg.fsf@gnu.org> Reply-To: Toby Cubitt NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: ger.gmane.org 1388697318 25795 80.91.229.3 (2 Jan 2014 21:15:18 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Thu, 2 Jan 2014 21:15:18 +0000 (UTC) Cc: esr@thyrsus.com, kfogel@red-bean.com, emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Jan 02 22:15:26 2014 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Vypbx-0004R4-7p for ged-emacs-devel@m.gmane.org; Thu, 02 Jan 2014 22:15:25 +0100 Original-Received: from localhost ([::1]:47044 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Vypbw-0002rM-K0 for ged-emacs-devel@m.gmane.org; Thu, 02 Jan 2014 16:15:24 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:57233) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Vypbp-0002r3-2b for emacs-devel@gnu.org; Thu, 02 Jan 2014 16:15:21 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Vypbj-0003GM-Kr for emacs-devel@gnu.org; Thu, 02 Jan 2014 16:15:17 -0500 Original-Received: from sanddollar.geekisp.com ([216.168.135.167]:15437) by eggs.gnu.org with smtp (Exim 4.71) (envelope-from ) id 1Vypbj-0003GC-HE for emacs-devel@gnu.org; Thu, 02 Jan 2014 16:15:11 -0500 Original-Received: (qmail 16672 invoked by uid 1003); 2 Jan 2014 21:15:11 -0000 Original-Received: from localhost (localhost.geekisp.com [127.0.0.1]) by localhost.geekisp.com (tmda-ofmipd) with ESMTP; Thu, 02 Jan 2014 16:15:04 -0500 Content-Disposition: inline In-Reply-To: <83sit6xgfg.fsf@gnu.org> X-PGP-Key: http://www.dr-qubit.org/gpg-toby-pub.asc User-Agent: Mutt/1.5.22 (2013-10-16) X-Delivery-Agent: TMDA/1.1.11 (Ladyburn) X-Primary-Address: toby@dr-qubit.org X-detected-operating-system: by eggs.gnu.org: OpenBSD 4.x-5.x [fuzzy] X-Received-From: 216.168.135.167 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:167083 Archived-At: 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: tsc25@cantab.net web: www.dr-qubit.org