Re: [PATCH v2] user-manual: mention git gui citool (commit, amend)

[Robin Rosenberg <robin.rosenberg.lists@dewire.com>]

måndag 06 augusti 2007 skrev J. Bruce Fields:
> On Mon, Aug 06, 2007 at 01:26:21AM +0100, Johannes Schindelin wrote:
> > On Sun, 5 Aug 2007, J. Bruce Fields wrote:
> > > A big warning would be out of place in what is for now just an isolated
> > > sentence in two different places.  But I agree with you that this would
> > > be worth mentioning in any eventual full-fledged git-gui tutorial.
> > 
> > Unfortunately, I am really wasted by this weekend's efforts to bring 
> > msysgit.git along... could you be so kind as to cut&paste the relevant 
> > section in a reply to me, so I do not have to search for myself?
> 
> Sure; appended.  This isn't that different from Steffen's proposal.
> 
> > I would not normally ask for such a favour; it is relatively easy to go on 
> > a search with Git, but I do have only 8 hours of sleep in the last 60 
> > hours under my saddle...
> 
> Hm.  On the other hand, maybe we should just be refusing to feed your
> addiction till you get some sleep.
> 
> I wanna keep this short for now, so if we really think we shouldn't
> mention of the hunk-selection thing without a warning, I'd rather just
> omit mention of it, and go for something like: "You can also use
> gitlink:git-gui[1] to create commits and view changes in the index and
> working tree", and drop the second hunk.  Whatever.

Who reads manuals for GUI's? Rougly nobody, unless the user needs the gui 
badly AND the GUI sucks badly. Manuals for GUI's are mostly tick-in-the-box 
documentation (which is the probably reason most GUI documentation suck too).

Uncommon/dangerous features should generally be harder to find, but can you 
can also use the common pattern of popping a dialog explaining the dangers 
and forcing the user to click away the box. Of course there should be a 
checkbox in the dialog "[X] Void warranty and don't bother me with this 
question anymore."

Nevertheless the dangers should be explained somewhere, maybe in the git user 
manual. I believe most people will learn from experience.

-- robin