git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / Atom feed
From: frederik@ofb.net
To: Jonathan Nieder <jrnieder@gmail.com>
Cc: Eric Sunshine <sunshine@sunshineco.com>,
	git@vger.kernel.org, "Robert P. J. Day" <rpjday@crashcourse.ca>
Subject: Re: de-alphabetizing the documentation
Date: Tue, 24 Jul 2018 12:52:18 -0700
Message-ID: <20180724195217.GA9366@ofb.net> (raw)
In-Reply-To: <20180708010926.GK6343@ofb.net>

Hello Jonathan,

Thank you for replying to me earlier. I just wanted to follow up on
this thread. Did you decide not to go with my proposal?

Next week I should have time to send you a patch with the manual page
reordered... although, unless you have a special 'diff' which can
detect when text has been moved from one place to another, I'm
guessing it would take you even longer to check the validity of the
patch than it would for me to create it.

However, I'm happy to do this or whatever other small projects you
would like to delegate as far as improving readability of your
documentation. I just need to know what is likely to be accepted.

Thanks,

Frederick

On Sat, Jul 07, 2018 at 06:09:26PM -0700, frederik@ofb.net wrote:
> Hi Jonathan,
> 
> If it's really just a matter of needing someone with a newcomer's
> perspective, then I'd be happy to look over the ordering of the git
> subcommands. You can run the command I provided to glean the frequency
> of each subcommand from your shell history, I'll look over the output
> and see if the ordering makes sense to me, and then you or someone
> else can rearrange the manual page to list the subcommands in this
> order. Is that a suitable plan?
> 
> Thanks,
> 
> Frederick
> 
> On Fri, Jul 06, 2018 at 04:47:15PM -0700, Jonathan Nieder wrote:
> > Hi,
> > 
> > Frederick Eaton wrote:
> > 
> > >       Unfortunately my contribution will have to be limited for the
> > > moment to making this suggestion, as I am extraordinarily busy. I hope
> > > it will not be too burdensome to add this item to your TODO list and
> > > keep it there until a willing volunteer comes along.
> > 
> > No problem.  If you have time to contribute later, we can wait. :)
> > 
> > > For what it's worth, I made extensive changes to the Arch Wiki Git
> > > article back in 2015, following an initial attempt of mine to
> > > understand various tutorials. It was the most prominent wiki-based Git
> > > documentation I could find at the time. The article has of course seen
> > > numerous improvements since then.
> > 
> > For reference: https://wiki.archlinux.org/index.php/git
> > 
> > > I don't think that it's really important to find a "best" ordering for
> > > commands or glossary terms; it's more a matter of finding someone who
> > > is willing to take responsibility for choosing a reasonable ordering.
> > > Presumably the head maintainer of this project could delegate the task
> > > to a qualified volunteer, not a newbie like myself but not necessarily
> > > someone with expert knowledge either.
> > 
> > I'd have to say, when I compare the troubles a new user and a
> > long-timer would run into, I conclude that the long-timers would be
> > more likely to produce worse documentation.  It is very difficult to
> > remember how new users see things.  The ideal skill set in fact has
> > nothing to do with level of Git expertise: to produce a good result, a
> > good technical writer would ask the right questions to gather
> > information from the experts and then test their documentation on
> > newcomers until it works well.
> > 
> > Based on the work you've described already having done, it sounds like
> > you'd be an ideal person to get this going, if you find yourself with
> > time for it.
> > 
> > >                                       It's too bad that a policy of
> > > not listing things alphabetically wasn't adopted from the beginning of
> > > this project, but I guess that's life.
> > 
> > From this thread I've been convinced that for this kind of reference
> > document, alphabetical organization within each section is a good
> > organization, provided each section is small enough (as in "git help"
> > output).
> > 
> > I'm also a fan of non reference documentation that can use a narrative
> > ordering instead (like "git help core-tutorial", except with more
> > modern commands).
> > 
> > > Thanks Eric for the pointer to "git help". This does indeed provide a
> > > finer and better grouping than the man-page (but it also looks like
> > > another candidate for de-alphabetization...!).
> > 
> > Indeed, copying that organization over from "git help" to the git(1)
> > manpage may be a good step for any interested people overhearing this
> > conversation.
> > 
> > As a first step, how about making git(1) recommend "git help", like
> > this?  It already recommends giteveryday(7) but the more interactive
> > first command might be useful for some people.
> > 
> > Thoughts?  Improvements?
> > 
> > -- >8 --
> > Subject: git doc: recommend "git help" as a starting point
> > 
> > The list of subcommands described in git(1) can be overwhelming.
> > Encourage newcomers to run "git help" to get a shorter list of
> > commands as a starting point.
> > 
> > Based on a suggestion by Frederick Eaton.
> > 
> > Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
> > ---
> >  Documentation/git.txt | 9 ++++++---
> >  1 file changed, 6 insertions(+), 3 deletions(-)
> > 
> > diff --git a/Documentation/git.txt b/Documentation/git.txt
> > index dba7f0c18e..0149ce9af0 100644
> > --- a/Documentation/git.txt
> > +++ b/Documentation/git.txt
> > @@ -23,9 +23,12 @@ unusually rich command set that provides both high-level operations
> >  and full access to internals.
> >  
> >  See linkgit:gittutorial[7] to get started, then see
> > -linkgit:giteveryday[7] for a useful minimum set of
> > -commands.  The link:user-manual.html[Git User's Manual] has a more
> > -in-depth introduction.
> > +linkgit:giteveryday[7] and run
> > +
> > +    git help
> > +
> > +for a useful minimum set of commands.  The link:user-manual.html[Git
> > +User's Manual] has a more in-depth introduction.
> >  
> >  After you mastered the basic concepts, you can come back to this
> >  page to learn what commands Git offers.  You can learn more about
> > -- 
> > 2.18.0.203.gfac676dfb9
> > 
> 

  reply	other threads:[~2018-07-24 19:54 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
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 [this message]
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=20180724195217.GA9366@ofb.net \
    --to=frederik@ofb.net \
    --cc=git@vger.kernel.org \
    --cc=jrnieder@gmail.com \
    --cc=rpjday@crashcourse.ca \
    --cc=sunshine@sunshineco.com \
    /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 the 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