Re: More documentation

[Han-Wen Nienhuys]

address@hidden writes:
> 
> 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).

We have some plans to redo the website, and our current efforts are in
the CVS module newweb (see
http://savannah.gnu.org/cgi-bin/viewcvs/lilypond/newweb/ , an older
version is available from http://lilypond.org/newweb/out/site/ ). We
also envision a FAQ under "About", which should address often
recurring general themes, like XML support, whether Lilypond =
musixtex, etc.
 
> 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.

The current document (on the web) is hard to navigate and looks
intimidating due to its sheer size, so we have a plan to reorganise
that as a subdirectory tree, e.g.

  input/
     beam
        cross-staff
        auto-beam
     chord-name
        entry
        output
        tweaking
     repeat
        percent
        volta
        midi

(etc.), This could be translated automatically into a structured TeX
document.

Comments? 

Those that wish to contribute can help with this, or help revise that
directory (things to look for: check all examples for currentness,
bugs, octavation, staffsize, clarity, brevity, places to link it from
the refman)

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

And, not wanting to sound too negative... It is very tempting and fun
to start something, but harder to finish it, and much harder to
continue maintenance.  Why not help with improving the current
tutorial and manual first? Once that's "finished" --and it's not by a
long shot, I've been editing it for the past few weeks-- you could
start new documentation that might fill gaps left.

Just to put this in perspective: a revised and updated manual, along
with reorganisation of the input/ directory is the only thing holding
back a 1.8 release.  If people would help with that, we would be able
to release 1.8 earlier.

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

Amen.


-- 

Han-Wen Nienhuys   |   address@hidden   |   http://www.cs.uu.nl/~hanwen