Re: [PATCH] git-reset.txt: Use uniform HEAD~N notation in all examples

From: Jari Aalto <jari.aalto@cante.net>
Date: Sep 1, 2007, 08:39 UTC
Message-ID: <hcmesrse.fsf@cante.net>
In-Reply-To: <7vy7frzfzg.fsf@gitster.siamese.dyndns.org>

Junio C Hamano <gitster@pobox.com> writes:

Show 14 quoted lines

> Jari Aalto <jari.aalto@cante.net> writes:
>
>> The manual mixed both caret(HEAD^) and tilde (HEAD~N) notation in
>> examples. This may be xconfusing to new users. The "counting" notation
>> HEAD~N likely to be grasped more easily because it allow successive
>> numbering 1, 2, 3 etc.
>
> I am mildly negative on this change.
>
> Referring to (rather, "having to refer to" to fix mistakes) the
> previous commit happens far more often than referring to an
> ancestor of an arbitrary generation away (i.e. HEAD~$n).  I
> think it is a better idea to expose users early on that HEAD^
> notation which is shorter to type.

If the page contains/combines many different ways of doing things, this creates confusion, especially if the distictions are not explained. And it would be unnecessary to explain the HEAD^ and HEAD~1 similarities in every page where these two get mixed.

PRICPLES:

1. The novice user is best served by making things simple and uniform.

2. Utilize concepts that may already be familar. E.g. other VCS/SCM tools
   have concept of counting back revisions with negative numbers: -1,
   -2, -3; so following this same idea in git manual pages would 
   already rang associated bells.

Like:

    HEAD, HEAD~1, HEAD~2

If the syntax is changed in the middle (as it was in manual page), that interrupts the kognitive flow of reading.

    HEAD, HEAD^, HEAD~2

I'm sure when user progresses with his learning, the differences or similarities of the notations become no-op.

But manual pages are served for wide audience. They are most important to new users.

I hope we could strive for KISS is possible.

-- 
Welcome to FOSS revolution: we fix and modify until it shines