Re: More documentation

[Mats Bengtsson]

> 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.

(Thanks for the acknowledgement.)

We have (or at least used to have) an FAQ list at 
http://www.lilypond.org/wiki/
which has the nice feature that everybody can make additions and
changes. However, this list is not very up-to-date and I guess that's
the main problem of a FAQ list in general, at least for a program like
Lilypond that's still rapidly evolving. Han-Wen and Jan still seem to
have the ambition to fix the problems in the program which means that
an FAQ entry often is outdated a few development releases later.

If we want to restart the FAQ list, I still think the Wiki solution
is to prefer. Unfortunately, I don't really have the time to support
the FAQ list more actively (maybe I would if I spent more time on the
list and less on answering similar questions over and over again).

Actually, the FAQ-like documentation that's most actively supported is
the "tips-and-tricks" and "regression test" documents. This, together
with the templates, is a very good source of extra information both for
new and experienced users, in my opinion.

> 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.

I have seen early drafts of one or two of the style specific tutorials
that people on the list have initiated. However, my main impression was
that the style specific part was very minor and that the main body of
the text was very general. However, I could see a need for more specific
documentation of Jürgen's ligature support, for example, once it's 
finished. Other examples could be "designing your own chord layout" or
"making the lute tab notation look the way I want it". Again, example
files and template files are often a better complement to the ordinary
manual than a separate document.

Instead of separate application areas, I'd rather suggest to split the
audiences into groups such as "I know almost nothing about computers"
up to "experienced programmer" or "I never read manuals, give me minimal
background to get started".

A final word: those who start writing their own tutorial should also
be prepared to actively support it once it's "completed" otherwise
it will very soon be outdated.

I apologize if I sound negative, it'd be great if we could have
even better and more diverse documentation.

   /Mats