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

[Johannes Schindelin <Johannes.Schindelin@gmx.de>]

Hi,

On Fri, 18 Jul 2008, Michael J Gruber wrote:

> 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?
> 
> 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".

Actually, I do not particularly like that direction.

Recently, somebody taught me that it makes sense, from the psychological 
view, to stress positive points, and avoid negative terms.

For example, "do not use this" -- even if followed by "use that instead" 
-- is suboptimal.  People will be more stressed, have a shorter attention 
span, and in general recall much less, if you use negative terms.

So what I really would like is this: leave the plumbing pages as they are, 
but enhance those pages that users (especially new ones) are likely to see 
most often.

By "enhancing" I mean to illustrate the principles and commands more in 
term of a select _few_ commands.  And they should describe the options 
themselves, instead of referring to plumbing man pages.

Maybe I'll find some time this weekend to write up a bit more of my 
tutorials, which I would then post so people see what I mean should be 
taught to n00bs first.

Ciao,
Dscho