Re: [PATCH] git-commit.txt: Order options alphabetically

From: Jari Aalto <jari.aalto@cante.net>
Date: Dec 2, 2010, 12:03 UTC
Message-ID: <87fwugs7pf.fsf@picasso.cante.net>
In-Reply-To: <20101202095324.34237fb2@jk.gs>

2010-12-02 10:53 Jan Krüger <jk@jk.gs>:

Show 8 quoted lines

> [Cc un-culled]
>
> --- Jari Aalto <jari.aalto@cante.net> wrote:
>
>> The reader have to guess "imagined groups"? Hm, that's interesting.
>
> Perhaps a more desirable (and agreeable) patch would introduce group
> subheadings, then?

Yes, that's the standard way of doing groups. Just like it's being done in other manual pages that are huge. But it is not being done in small manual pages. GNU project certainly doesn't in general.

I agree tat doing "groups" makes only sense on pages that have large number of options. For a screenful, it's more distracting than worth.

> In rev-list-related options we already have a couple of explicit
> groups.

I can't find that manual page or file under Documentation/, could you help here?

Show 10 quoted lines

>> [...] Git's command
>> line is inconsistent in many places and there is room for improvement.
>> Documentation is one way to spot those.
>
> That seems to be the only reason you've brought forward for alphabetic
> sorting
>
> In any case, the end user will probably be more often interested in
> appropriately grouped options than in being able to easily find
> inconsistencies between various commands.

Well. In my experience (having watched others to learn) the manual pages are not the source used for learning.

    - They are technical documentation
    - They are reference documentation
    - They are visited, then discarded, visited and discarded.

People primarily learn outside of manaula pages. No wonder Books are being written. Compare:

    - Have you seen the Web SVN book?
    - Have you seen the Web HG Book?

People go to the manual pages once they have a specific need for infomation and details. I could sketch these uses of manual pages:

    - Someone throws up a git command (IRC #git, Blogs, Web page). What
      do all those unreadable one letter options mean? Gosh they don't
      even mean the save accross different git* programs.

      > He searches manual pages A-Z, easy to spot all options. Not
      > interested in related things. He tries to understand the
      > command, script etc.

    - Someone is learning Git.

      > He certainly does not start from manual pages. Other soources of
      > information are more in to him. Besides  Windows does not have those.
      > We might guess what MySGIt as other do: they reach Google button.

      This person just wants to solve a problem, get things done, the
      faster the better. The easier the better, the less thinking the
      better.

    - Geek. He wants to learn inside out.

      > He digestestes all. Related options, related pages, flipping
      > form man to man as he knows all the glory details is just there.

It all depends if it is desireable to make pages more approachable to the average group, or are they kept to serve only small core audience.

There are 100+ manual pages in the git distribution. You get even disoriented in shere numbers of them. And you have to throw dice to figure out in what page that information might be you are currently in need.

It's classical case of how to arrange information for easy retrieval. Think Libraries as model.

Jari