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

[Jari Aalto <jari.aalto@cante.net>]

2010-12-02 10:53 Jan Krüger <jk@jk.gs>:
> [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?

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