git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
From: Jonathan Nieder <jrnieder@gmail.com>
To: Frederick Eaton <frederik@ofb.net>
Cc: git@vger.kernel.org, "Robert P. J. Day" <rpjday@crashcourse.ca>
Subject: Re: de-alphabetizing the documentation
Date: Fri, 6 Jul 2018 14:16:00 -0700
Message-ID: <20180706211600.GB6195@aiede.svl.corp.google.com> (raw)
In-Reply-To: <20180706200423.GC6343@ofb.net>

Hi Frederick,

Frederick Eaton wrote:

> 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 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,

That doesn't seem like a useful order pedagogically, but

>                                             or in the reverse order of
> frequency of use by a typical Git user.

That does.

Currently the commands are already broken into a few categories:

  High-level commands
    Main porcelain commands
    Ancillary commands
    Interacting with others
  Low-level commands
    Manipulation commands
    Interrogation commands
    Synching repositories
    Internal helper commands

While it's alphabetical within each section, overall it is not
alphabetical at all!

Alas, there are plenty of "Main porcelain commands", and I think that
is where your question comes from.  It would be nicer to list just five
to start, say.

Some of the most thoughtful documentation that comes with Git is at
https://www.kernel.org/pub/software/scm/git/docs/user-manual.html.
It might be useful for inspiration.

Ideas?  If you start with a proposal, we're happy to help refine it.
People in the #git channel on irc.freenode.net (wechat.freenode.net)
might also be useful for inspiration in coming up with a proposal.

Each of us have our weaknesses for this kind of work: you're telling
me you're too new to have a sense of which commands are the first a
person would need to learn (and I have no reason to doubt you), while
many on this list would have the opposite problem of taking too much
for granted and not being able to put themselves in the mind of a
newcomer.  So we'll have to help each other.

tl/dr: if you come up with a proposed "first commands to learn"
category with some proposed commands to go in it, we'll be happy to
help you with the next steps.

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

Your help is welcome here as well.  Probably a similar kind of
categorization, with entries ordered either alphabetically or
according to some narrative in each section, would be the easiest to
maintain over time.

Thanks,
Jonathan

  reply	other threads:[~2018-07-06 21:16 UTC|newest]

Thread overview: 17+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2018-07-06 20:04 frederik
2018-07-06 21:16 ` Jonathan Nieder [this message]
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

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

  List information: http://vger.kernel.org/majordomo-info.html

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

  git send-email \
    --in-reply-to=20180706211600.GB6195@aiede.svl.corp.google.com \
    --to=jrnieder@gmail.com \
    --cc=frederik@ofb.net \
    --cc=git@vger.kernel.org \
    --cc=rpjday@crashcourse.ca \
    --subject='Re: de-alphabetizing the documentation' \
    /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

git@vger.kernel.org list mirror (unofficial, one of many)

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://public-inbox.org/git
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V1 git git/ https://public-inbox.org/git \
		git@vger.kernel.org
	public-inbox-index git

Example config snippet for mirrors.
Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.version-control.git
	nntp://ou63pmih66umazou.onion/inbox.comp.version-control.git
	nntp://czquwvybam4bgbro.onion/inbox.comp.version-control.git
	nntp://hjrcffqmbrq6wope.onion/inbox.comp.version-control.git
	nntp://news.gmane.io/gmane.comp.version-control.git
 note: .onion URLs require Tor: https://www.torproject.org/

code repositories for project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

AGPL code for this site: git clone https://public-inbox.org/public-inbox.git