git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Jonathan Nieder <jrnieder@gmail.com>
To: Felipe Contreras <felipe.contreras@gmail.com>
Cc: Junio C Hamano <gitster@pobox.com>,
	git@vger.kernel.org, Michael J Gruber <git@drmicha.warpmail.net>,
	"J. Bruce Fields" <bfields@fieldses.org>,
	Hannu Koivisto <azure@iki.fi>, Jeff King <peff@peff.net>,
	Wincent Colaiuta <win@wincent.com>,
	Matthias Lederhofer <matled@gmx.net>
Subject: Re: [PATCH v2 0/2] user-manual: new "getting started" section
Date: Sun, 25 Oct 2009 06:14:38 -0500	[thread overview]
Message-ID: <20091025111438.GA11252@progeny.tock> (raw)
In-Reply-To: <94a0d4530910250243k4cbc3c18l5e018a05e5afdb2d@mail.gmail.com>

Hi Felipe,

Felipe Contreras wrote:

> I disagree. I think it's awfully useful to have color.ui = auto
> configured before reading the multitude of 'git branch', 'git show',
> and 'git diff' commands that are presented on first two sections. So
> useful, in fact, that I think it should be enabled by default.

This is why I think you had a good idea here.  When a program doesn’t
behave as I would like, it can be very comforting to know where its
dotfile is and be able to edit it (I’m not sure how I learn this for
most programs).  And it is much easier to parse git output without
reading it all when color is turned on, so that is a setting I imagine
could be useful to people.

On the other hand, it is far more pleasant to use a program that
doesn’t need configuration at all.  And as I mentioned before, it is
best to avoid wasted time at the beginning of the manual.

> Supposing that color.ui is 'auto' by default,

Should it be?  I think it would not be too hard to detect a color
terminal by checking $TERM.  Are many people bothered by color?  Do we
need some way to make it more obvious how to turn color _off_?

> No, but "improving" needs "changing", and the discussion I see is
> biased towards "not changing".
[...]
> I don't think the user manual is achieving that purpose. I don't know
> if it's the user manual's fault, or git's UI. Both areas need a lot of
> improvement (as the git user survey suggests), and I've tried to
> improve both with a lot resistance in both. So I'm not very hopeful
> anymore.

I hope you have not misunderstood.  I cannot speak for everyone else
here, but I know I am happier when (1) fixes match problems to be
solved in a documented way and (2) fixes do not unnecessarily break
unrelated habits.  One way to bring this about is to justify each
change by explaining what real problem it will solve and how it avoids
collateral damage.  Without that justification, a change is indeed
dangerous and might be worth resisting until it gets clarified.  But
this is not meant to prevent fixes from occuring at all.

Could you list some UI patches that were overlooked or not properly
addressed?  Maybe people just forgot about them or were waiting for an
updated version, or maybe the problems some solve weren’t articulated
clearly yet.  I would be glad to help out in any way I can.

> However, I haven't met any proficient git user that got to that point
> by reading the user manual, so I think it must be completely
> re-thought.

I have met one.  (Well, he read the git tutorial and learned by using
git, too.)  I think the user manual’s pretty well written, though it
certainly has its gaps and rough spots.

> Judging from the luck I've had pushing even the simplest
> changes I don't think it will improve much more, unfortunately.

Even the simplest changes can be hard.  But I hope they do not amount
to nothing.  I hope at the very least the git-config manual page will
improve...

Thank you for working on this.  I hope you succeed in improving git’s
usability, one way or another.

Regards,
Jonathan

  reply	other threads:[~2009-10-25 11:05 UTC|newest]

Thread overview: 28+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2009-10-24  9:44 Felipe Contreras
2009-10-24  9:44 ` [PATCH v2 1/2] user-manual: add global config section Felipe Contreras
2009-10-24  9:44 ` [PATCH v2 2/2] user-manual: simplify the user configuration Felipe Contreras
2009-10-24 13:06 ` [PATCH v2 0/2] user-manual: new "getting started" section Nanako Shiraishi
2009-10-24 14:08   ` Felipe Contreras
2009-10-24 14:14     ` Björn Steinbrink
2009-10-24 14:22       ` Felipe Contreras
2009-10-24 17:51 ` Junio C Hamano
2009-10-24 18:19   ` Junio C Hamano
2009-10-24 20:16     ` Felipe Contreras
2009-10-25  0:26       ` J. Bruce Fields
2009-10-25  3:08       ` Junio C Hamano
2009-10-25  9:43         ` Felipe Contreras
2009-10-25 11:14           ` Jonathan Nieder [this message]
2009-11-11 23:15             ` Felipe Contreras
2009-11-12 11:29               ` Michael J Gruber
2009-11-12 20:04                 ` Felipe Contreras
2009-11-13 21:06                 ` Nanako Shiraishi
2009-11-16 22:52                   ` Felipe Contreras
2009-11-17 12:06                     ` Nanako Shiraishi
2009-11-17 17:28                       ` J. Bruce Fields
2009-11-17 18:25                         ` Junio C Hamano
2009-11-17 22:00                           ` Felipe Contreras
2009-11-17 22:19                             ` Junio C Hamano
2009-11-17 23:06                               ` Felipe Contreras
2009-11-17 23:13                                 ` Junio C Hamano
2009-11-18  0:05                                   ` Felipe Contreras
2009-11-17 17:53                       ` Matthieu Moy

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20091025111438.GA11252@progeny.tock \
    --to=jrnieder@gmail.com \
    --cc=azure@iki.fi \
    --cc=bfields@fieldses.org \
    --cc=felipe.contreras@gmail.com \
    --cc=git@drmicha.warpmail.net \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=matled@gmx.net \
    --cc=peff@peff.net \
    --cc=win@wincent.com \
    --subject='Re: [PATCH v2 0/2] user-manual: new "getting started" section' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).