Re: Suggestion: doc restructuring [was: Re: Considering teaching plumbing to users harmful]

From: Jon Loeliger <jdl@freescale.com>
Date: Jul 18, 2008, 18:26 UTC
Message-ID: <4880E041.8070001@freescale.com>
In-Reply-To: <48806D03.30603@fastmail.fm>

Michael J Gruber wrote:

Show 28 quoted lines

> Johannes Schindelin venit, vidit, dixit 16.07.2008 19:21:
> ...
>>
>> Am I the only one who deems teaching plumbing to users ("I like it 
>> raw!  So I teach it the same way!") harmful?
>>
>> Ciao,
>> Dscho "who is sad"
> 
> In an attempt at making not only Dscho happier I suggest a restructuring 
> of the man pages in the following way:
> 
> In each man page, put a note which says something like:
> "This is part of linkgit:gitplumbing[7]." and the like
> It should be in a prominent place, such as the last line of "DESCRIPTION".
> 
> gitplumbing[7] etc. pages should contain:
> - a definition of the respective term together with appropriate usage 
> advice (regular use/scripting..., "Let there be dragons.")
> - a list of commands like we have in git[1] right now
> 
> With the current situation, people don't look at git[1] in order to find 
> out what they're supposed to use. It's too long anyways, and could link 
> the above pages instead.
> 
> If there's enough interest/agreement I'd come up with a refactoring patch.
> 
> Michael

I'd like to throw my beef with the main Git man page out there for consideration as well...

When I hit the man page, which I do on line quite frequently, I usually use it as an index to get to the real, current man page for a particular command. (I am at git.kernel.org for other reasons all the time, so it is convenient.)

The current sub-setting and organization is painful because it doesn't have a comprehensive, linear, alphabetized list of commands from which to select the real man page. I never know which "section" to find a given command. Is it an Ancillary "manipulator" command? Or maybe just a "Manipulation" command, or maybe an "Interrogation" command? A "Helper"?

I always have to painfully search the page for it instead.

I'm not saying get rid of the Categorical organization. I am saying, we need a first-page with a straight, alphabetized command index somewhere easy and located conveniently.

Thanks for listening, jdl