From: "Philip Oakley" <philipoakley@iee.org>
To: "Junio C Hamano" <gitster@pobox.com>
Cc: <git@vger.kernel.org>, "Ramkumar Ramachandra" <artagnon@gmail.com>
Subject: Re: What's cooking in git.git (Mar 2014, #03; Fri, 14)
Date: Tue, 18 Mar 2014 00:16:19 -0000 [thread overview]
Message-ID: <D6ED63739391422AAAB3B863AA9626CB@PhilipOakley> (raw)
In-Reply-To: xmqqd2hkg2qw.fsf@gitster.dls.corp.google.com
From: "Junio C Hamano" <gitster@pobox.com>
> "Philip Oakley" <philipoakley@iee.org> writes:
>
>>> * po/git-help-user-manual (2014-02-18) 1 commit
>>> - Provide a 'git help user-manual' route to the docbook
>>>
>>> I am not sure if this is even needed.
>>
>> My rhetorical question would be "what should 'git help user-manual'
>> do?" for the beginner, ...
>
> Why would any _beginner_ even be expected to ask "git help"
> everything, including "user-manual", in the first place? Wouldn't
> things like /usr/share/doc/git-doc/ be the place to help them in a
> consistent manner across different programs instead?
It would be my view that 'git help' would be the first place for a
_beginner_ to start. In some ways it depends on what background one
expects the beginner to have, and whether they know well their way
around their machine, which often isn't the case.
Given that Git is available on many systems as a packaged application,
the user may not even know where the raw documentation is held. That's
certainly likely for those on Windows ;-)
>
>> ... do we have a sort of policy on ensuring
>> that the majority of user documentation should be available (or at
>> least referenced) via the 'git help' mechanism?
>
> I doubt that there should be such a policy.
>
> "git help" is primarily to show the manual pages, and some technical
> details docs that are referenced from manpages may need to be
> reachable from it.
My approach, as you may have gathered, would be that the basic
documenation should at least be available via a 'git help <something>'
mechanism, even if advanced users already use alternative means suitable
to their expertise.
> The user manual, on the other hand, may
> reference individual manpages but because it is primarily a document
> that shows the overall flow to employ different commands, individual
> manpages referring to the user manual feels entirely the other way
> around.
Ideally (from my viewpoint) there would be a way to directly access the
current "user-manual" via the 'git help'. It's whether special casing
the user-manual would be sensible.
At the moment 'git help' prompts for 'git help -g' which then lists the
leading guides (I have a -gg option to list all guides in draft), so
beginners who read the prompts would at least be led to the tutorial,
which does have an extra link into the user-manual. Otherwise it's
catch-22 - if a user doesn't know it's there they might never find it.
One has to lead the horse to the water before it can drink, even though
some never do ;-)
next prev parent reply other threads:[~2014-03-18 0:16 UTC|newest]
Thread overview: 17+ messages / expand[flat|nested] mbox.gz Atom feed top
2014-03-14 22:09 What's cooking in git.git (Mar 2014, #03; Fri, 14) Junio C Hamano
2014-03-15 8:15 ` Torsten Bögershausen
2014-03-17 17:01 ` Junio C Hamano
2014-03-19 10:53 ` Max Horn
2014-03-19 12:32 ` Max Horn
2014-03-19 17:04 ` Junio C Hamano
2014-03-19 17:21 ` Max Horn
2014-03-19 18:53 ` Junio C Hamano
2014-03-15 12:34 ` Duy Nguyen
2014-03-17 18:05 ` Junio C Hamano
2014-03-16 18:30 ` Philip Oakley
2014-03-16 23:15 ` Ramkumar Ramachandra
2014-03-17 18:01 ` Junio C Hamano
2014-03-17 22:41 ` Philip Oakley
2014-03-17 17:21 ` Junio C Hamano
2014-03-18 0:16 ` Philip Oakley [this message]
2014-03-18 4:40 ` Jeff King
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=D6ED63739391422AAAB3B863AA9626CB@PhilipOakley \
--to=philipoakley@iee.org \
--cc=artagnon@gmail.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
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).