mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
* de-alphabetizing the documentation
@ 2018-07-06 20:04 frederik
  2018-07-06 21:16 ` Jonathan Nieder
  0 siblings, 1 reply; 17+ messages in thread
From: frederik @ 2018-07-06 20:04 UTC (permalink / raw)
  To: git

Dear Git Developers,

I am trying to learn how to use Git but I've been put off by not
knowing where to start. I would like to start with the 'git' man page,
but it lists the Git subcommands in alphabetical order, rather than in
an order which would be useful for learners. For example, I'm not sure
how often 'git bisect' is used, but it is strange to see it listed
before 'git init' and 'git clone'.

I know that 'gittutorial' exists, and I've indeed worked through it
and some other Git tutorials. However, these are more like lists of
examples that should come at the end of a typical manual page. I don't
think they are intended as canonical references for the program
functionality. At some point I would like to use the main 'git' manual
page as my primary source of documentation. This would be easier if it
were designed to be read straight through.

I wonder if someone familiar with Git could list the commands in an
order which makes more sense for learning, for example in the order in
which they were invented by Git developers, or in the reverse order of
frequency of use by a typical Git user. This could easily be derived
from the shell history of someone who is reading this.

    (cat ~/.bash_history; cut -d ";" -f 2 ~/.zsh_history) | grep '^git ' | cut -d ' ' -f 2 | sort | uniq -c | sort -nr

I would like to have this list for personal use, but once it is
created, perhaps someone could also add it to the main Git man page.
The list could be added at the top of the "GIT COMMANDS" section.
Alternatively, and I think preferably, the entries in that section
could be rearranged into this order.

Finally, perhaps the same listing and/or reordering could be done for
other important manual pages, like 'gitglossary'. Presumably
'gitglossary' should be sorted topologically, so that each term is
defined prior to any terms depending on it.

I'm not sure why alphabetical order was decided upon, but it seems
less than useful in the information age, when people can easily search
for text electronically. Maybe at some point someone decided to "clean
up" the presentation by alphabetizing the manual page. As a user who
is more concerned with substance, it is annoying to encounter such an
emphasis on the superficial, which seems unworthy of such an important
piece of software.

Thank you,

Frederick Eaton

^ permalink raw reply	[flat|nested] 17+ messages in thread

end of thread, other threads:[~2019-03-11 14:38 UTC | newest]

Thread overview: 17+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2018-07-06 20:04 de-alphabetizing the documentation frederik
2018-07-06 21:16 ` Jonathan Nieder
2018-07-06 21:18   ` Jonathan Nieder
2018-07-06 23:21     ` frederik
2018-07-06 23:47       ` Jonathan Nieder
2018-07-08  1:09         ` frederik
2018-07-24 19:52           ` frederik
2018-07-24 21:11             ` Jonathan Nieder
2018-08-11  2:30               ` frederik
2018-08-13 18:17                 ` Junio C Hamano
2019-02-19 17:54                   ` [PATCH 0/1] de-alphabetize command list Frederick Eaton
2019-02-21 18:05                     ` frederik
2019-03-11  9:04                       ` frederik
2019-03-11 14:38                         ` Jacob Keller
2019-02-19 17:54                   ` [PATCH] Prioritize list of commands appearing in git(1), via command-list.txt. Don't invoke 'sort' in Documentation/cmd-list.perl Frederick Eaton
2018-07-07  4:25       ` de-alphabetizing the documentation Theodore Y. Ts'o
2018-07-06 21:32   ` Eric Sunshine

Code repositories for project(s) associated with this public inbox

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 read-only IMAP folder(s) and NNTP newsgroup(s).