Re: Absolute Beginners

[John Mandereau]

Le jeudi 28 décembre 2006 à 15:13 +0100, Manuel a écrit :

[...]
> "See this, I show you, do thus, note the ripples" - That's teaching!  
> - but only good teaching if the teacher knows where he is taking you.

You're effectively focused on teaching in your tutorial, which is a very
good point!


> A most frustating thing when trying to use the tutorial is that the  
> proposed examples just too often don't compile as they supposedly  
> should, as with the very first example.

Agreed. IMHO, the "First steps" section is not really a piece of
tutorial, but rather a quick tour of basic ly syntax, a bit like the
crash course on http://lilypond.org/web/switch/howto


> Although I agree that having one didactical introduction and one  
> reference work is a good idea, don't forget that even a reference  
> work must be somewhat didactical, since even the expert is learning.

No, a real reference is pure information (I mean information without any
didactical or pedagogical blurb), from which the expert extracts the
useful bits when needed. That's what a reference is for, at least this
is to me the right definition.


> To split the chapter into several HTML sections is possible. Due to  
> my lack of experience, I don't see why not use the .pdf format for  
> downloading, or HTML format for the whole chapter in one page (indeed  
> there is now the whole tutorial in a single HTML document). The  
> splitting would nevertheless necessitate further elaboration.

Don't worry about format issues; the Texinfo source format, used to
document most of GNU software (including LilyPond), can be processed to
render 3 output formats:
- plain text for on-screen viewing
- HTML, both splitted and in a single page
- PDF (rendered by TeX)


>  In any  
> case, I believe in field-testing and in test-versions (called beta, I  
> suppose). One possibility would be to offer the first and following  
> chapters (I have started work on a second chapter now that the first  
> has reached at least a first completion) perhaps creating a  
> beginner's section in the documentation, maybe "LilyPond's Nursery  
> Slopes".

If you really want to add it to official documentation, it should be
written in Texinfo. That's not difficult to do as long as you know
Texinfo, or somebody experienced enough will do that. Of course, this
technical issue is a minor point, because it's a consequence of the
biggest issue: which presentation and which hosting your work deserves
(see below).



> To insert parts of the beginners guide into the present tutorial  
> would cancel most of its didactical, "take-you-by-the-hand"  
> structure, which should hang together to be clear and useful, instead  
> of being cut and mixed with parts of another work, however good,  
> written at another time and with other concepts in mind. But yes, one  
> didactical help and a deeper going reference work should be enough in  
> general terms. I can't really say, but as a general idea, could the  
> present, official tutorial be merged with the present reference  
> document? I say this because the tutorial is already a rather  
> reference-oriented work. Indeed I thought that its last part was the  
> reference document itself.

I don't totally agree when you say the official tutorial is a reference
work, I'd rather say it intends to quickly show Lily notation features
with concrete applications (a lead sheet and an orchestral score with
parts). It's not perfect, but it explain well concepts like nested music
expressions. Maybe you call _reference_ this kind of explanation? This
is certainly not. These explanations are maybe mathematically- or
programmingly-minded (that's not surprising because the ly format is a
kind of language) so it may take some people time to assimilate.
I guess you wouldn't explain Lily concepts this way; is this why you say
the "Absolute beginners" tutorial couldn't replace the official one?

If this and other issues like style (your work shows much more detailed
intructions) really matter, there could be two tutorials in Lily docs,
with two different styles; but their contents shouldn't overlap each
other, so that new users can read one tutorial, then the other without
wasting their time.



> So yes, I would like to go on working on this. I would need some help  
> though, when I cannot figure something for myself, like it happened  
> with the Da Capo thing. Of course I'll look it up in the manual first.

You will certainly get help on the list. Chapter one is already great
work, good luck for the next ones!


My offer to integrate your work into the official tutorial was
premature, as it is not clear now how to integrate it (or add it) into
the official docs, that's why I second Joe and Graham's suggestion: the
ideal current hosting of your work is certainly a wiki, for example
http://lilypondwiki.tuxfamily.org/ If you need help for adding your work
there, just ask me ;-)


-- 
John Mandereau <address@hidden>