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

From: Michael J Gruber <michaeljgruber+gmane@fastmail.fm>
Date: Jul 18, 2008, 10:14 UTC
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: ...

Show 6 quoted lines

> 
> 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? ;)