Re: [doc] User Manual Suggestion

From: Björn Steinbrink <b.steinbrink@gmx.de>
Date: May 3, 2009, 01:48 UTC
Message-ID: <20090503014826.GE6135@atjola.homenet>
In-Reply-To: <b4087cc50905021810y28ab2019ob99857670383ba46@mail.gmail.com>

On 2009.05.02 20:10:14 -0500, Michael Witten wrote:

Show 19 quoted lines

> 2009/5/2 Björn Steinbrink <B.Steinbrink@gmx.de>:
> >> > Hm, like chapter 7 "Git concepts"?
> >>
> >> That's exactly the problem. It should be in chapter 0.
> >
> > I'm not opposed to re-ordering stuff. Though I often think that having
> > commands and concepts "together" is better.  Maybe we just need that
> > twice? Once the plain data model, and once a "hands on" version where
> > the effects of the commands are described in terms of the data model.
> >
> > The former "sucks" for those that want to just "dive in" (but might
> > still be happy to get told what their actions do), the latter sucks when
> > you just want to look something up.
> 
> Indeed. I think the key is to split up the documentation for these 2 paths.
> 
>     http://marc.info/?l=git&m=124058631814726&w=2
> 
> The mixing of the 2 is what makes everyone unhappy.

I'm not sure which part of that email you're referring to (and I'm getting tired, 3:20am...). I'm just seeing the paragraph where Jeff has said that we have a split, between the tutorial and the manual. And what I tried to said, is that we might need the tutorial to be less of a "recipe collection", but more of a hands-on introduction that actively explains the data model and how data is manipulated by using the commands. And the user manual might become less example oriented, focussing more on concepts, giving examples in addition. So that we have both approaches, hands-on and theoretical, but both keeping the data model in mind, at least to some extend.

For example the "hands on" version might rather create a "toy" repository than importing an existing project right away, to get a smaller scope of things to describe at once, and to be able to show e.g. full "graphs" of the early repo as it evolves. Users that simply don't want to care can still skip over the explanations and suffer^Wjust pick up the commands. You could e.g. say "To create a lightweight tag you use ..., which adds a new reference, while ... adds an annotated tags, which is a real tag object, with a message and a tagger and which can possibly be signed using your GPG key." And maybe explain the tag object a bit further.

While the manual might, for example, have a section "Tags" instead of the current "Creating tags"(*), where the different types of tags are described, how they fit into the data model, what the different types of tags mean, and only then give examples how to create them.

Lots of possible work...

Björn

(*) Why's that in the "Exploring git history chapter"? Let's see if I can sort out my local asciidoc problems and find some time to provide some basic patches for that. Though I still haven't managed to get the one for the git-push man page done... *sigh*