From: Michael J Gruber <michaeljgruber+gmane@fastmail.fm>
Date: Fri, 18 Jul 2008 10:14:27 GMT
Subject: Suggestion: doc restructuring [was: Re: Considering teaching plumbing to users harmful]
Message-ID: <48806D03.30603@fastmail.fm>
In-Reply-To: <alpine.DEB.1.00.0807161804400.8950@racer>

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


P.S.: For me
porcellaine = artistic, fragile
plumbing = plain, robust
Which one would you choose for daily hard work? ;)