More documentation

[Graham Percival]

(this has been sent to lilyond-user and -devel, since it may be of
interest to some people who only read -user.  Replies should be sent to
-devel only, since it's really a devel matter)

Hi guys,
Many of us have thought about writing more documentation for Lilypond. 
In fact, almost everybody I've talked to via private mail about Lilypond
has said that they're either thinking or writing such documents. 
Including myself.

The main cause of these ideas is that the existing manual is a reference
manual -- a good place for looking up stuff you've forgotten, but not so
great for learning the material in the first place.  Various people have
talked about extending the tutorial to cover more material,
restructuring the existing docs, writing a completely seperate book,
maintaining seperate "style-specific" pages (ie one page for string
writing; another for piano issues, etc), and other ideas.

I thought that it might be a good idea to discuss these ideas and
perhaps work together on them.  My main hope is that we'll actually
get some alternate documentation done, rather than merely thinking
about it.  :)


I have two ideas for new documentations:
1)  a FAQ that's really just a bunch of saved emails from lilypond-user.
Whenever we (and by "we", I mean "/Mats" :)  answer a difficult question
on the email list, we add that message to the FAQ.  That way there's a
shorter list of emails to search than looking through the whole archive
of lilypond-user.
2)  Writing a "learning Lilypond" book, based on the tutorials.  To make
this easy to collaborate on, I suggest that structure the book with
distinct sections which have prerequisites.  Kind-of like university
courses (ie before you can take MATH 332, you need to take MATH 152 and
232), or even like technologies in Civilization and Freeciv.  :)
For example, after you've learned the basic notation, you could either
read the section on lyrics, or the section on piano music, or writing
for strings.
Once we decide how the structure (or "technology tree", using the civ
analogy) should look, it should be easy to write sections independantly.


So if you're interested, join lilypond-devel (if you haven't already)
and share your ideas.

Cheers,
- Graham