Re: Absolute Beginners

[Graham Percival]

Manuel wrote:
> Graham, I see that you are in charge of documentation. I suggest that 
> the little "Absolute Beginners' " help we have been tossing around for 
> the last couple of days be included in the documentation. What is your 
> opinion?

The entire "absolute beginners" chapter is longer than other doc 
submissions we've had recently, and it's not clear to me how it would 
fit into the existing structure -- does it simply replace sections 2.1 
and 2.2 (and 2.3?), or would any material from those sections need to be 
kept?  Also, if it were to be included in the current tutorial, it would 
need to be split into smaller sections.

I see three options:
1.  "beginners" expanded until it forms a complete independent tutorial; 
we then remove the old tutorial and replace it with the new one.
2.  "beginners" is split into small sections so that we can easily see 
how it replaces or alters the current tutorial; we add new tutorial 
sections when each one is ready.
3.  I take ideas from the "beginners" chapter and modify the existing 
tutorial accordingly.


The question of which option is best depends on what you want to do.  #3 
is the fastest way to include the ideas from "beginners" in the user manual.

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!), then #2 would be a 
better way to go -- it would be a good introduction to the process of 
creating lilypond documentation.

I don't recommend #1; writing documentation takes a lot more time and 
effort than most people realize.  You could easily spend 50 hours 
working on a complete new tutorial before it was ready to replace the 
old one.

#1 and #2 would require somebody (possibly you, possibly somebody else 
on this list) to create patches to the documentation source files.  The 
documentation is written in a language called Texinfo.
http://www.gnu.org/software/texinfo/

For an example, go to the lilypond source code:
http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=tree

and select "Documentation", "user", and then examine "tutorial.itely".


Cheers,
- Graham