Re: Absolute Beginners

[John Mandereau]

Le mercredi 27 décembre 2006 à 17:13 +0100, Manuel a écrit :
> Graham, I think the present tutorial is an excellent piece of work as  
> it is, only unclear in certain parts for beginners like me. It looks  
> like it was made by people with deep and systematic knowledge of the  
> matter but less didactical experience. I like the idea to try and  
> expand "beginners" and see what happens.

"deep and systematic knowledge of the matter" as you say doesn't qualify
well a tutorial but rather a reference. I'd say official Lily tutorial
isn't always wordy enough: in some sections, a lot of important details
are not explicited. In my humble opinion, a quick comparison between the
official tutorial and your work shows these offending sections:

- in "Running LilyPond for the first time", there isn't enough details
about how to run LilyPond, which differs depending on the platform.

- in "First steps", there isn't enough emphasis on syntax correctness:
many Lily newbies are certainly not programmers, or even haven't learnt
any programming language.



> I don't understand in which way the first chapter is too long.  
> Didactically speaking it is as short as it can be, and you surely  
> don't  mean the file size?

Graham cezrtainly means the chapter should be splitted into several
sections, just like the current Lily HTML docs (one small section per
page).



> To insert patches would seriously compromise the clarity for the  
> adresees.

What do you mean? Aren't patches the best way to see changes?



> > If you're interested in doing more doc work (say, an hour or two a  
> > week; if you'd like to do more that's totally welcome!)
> 
> Yes, if I understand you correctly: would you call what I have being  
> doing "doc work"?

Of course you have! In my opinion your work helps criticizing and
improving the current tutorial (see below). Keep up the good work and go
on suggesting doc improvements/additions!



> But let me explain: once a beginner understands correctly how the  
> program works, he can go ahead and use a reference work, as is  
> already contained in the tutorial. Then he is no longer a beginner,  
> but a user (both have quite different support needs). This process I  
> find not easy to do with the tutorial if you don't know anything  
> about command-line programs, for instance.
> 
> One didactically-oriented beginners guide can coexist with the  
> reference-oriented tutorial, I think.

I'm against having two tutorials: a reference-oriented tutorial is no
longer a tutorial, and there is already a reference manual. There are
already enough sources of information to make beginners lost.

I'd vote for Graham's proposal #2: splitting your work into small
sections and merging them into the tutorial. If the matter is making
patches, I volunteer to do that, as I've already been working in the
docs for French translations. Of course, this requires you accept that
your work is integrated into LilyPond docs.


> A guide for total beginners might even take a load off the support  
> guys, but could also encourage more people to use LilyPond. Some of  
> my colleagues wouldn't mind paying hundreds of euros for a commercial  
> program if it is easier to use, which it isn't, but it looks easy  
> because of the graphic interface toys.

I totally agree with you.


Cheers,
-- 
John Mandereau <address@hidden>