Re: [doc] User Manual Suggestion

["Björn Steinbrink" <B.Steinbrink@gmx.de>]

On 2009.05.02 20:10:14 -0500, Michael Witten wrote:
> 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*