Re: FAQ for LilyPond

[Cameron Horsburgh]

Graham Percival wrote:
> On 19-Mar-06, at 4:57 PM, Cameron Horsburgh wrote:
>
> > For the last few weeks I've been toying with the idea of beginning an 
> > FAQ for LilyPond. I haven't really done much yet, besides flag a few 
> > questions on the LilyPond lists that might be good candidates.
> >
> > Before I start doing anything serious:
> > 1) is there a reason why this hasn't been done before?
>
> There's no need?  ... or rather, having one more piece of documentation 
> is the last thing we need?
>
> LilyPond documentation:
> - manual
> - examples on lilypond website
> - LSR
> - examples on mutopia
> - mailing list archives
> - lilypond wiki

You're right--there is a bit out there. I didn't even realise the wiki 
existed, and it seems to be similar to what I had in mind. I'm thinking 
of the newbie who might run into any one of several dozen problems that 
could be the difference between them persevering and giving up.

A newbie isn't likely to get much help from mutopia, the archives can be 
difficult to search sometimes (especially in recent months ;-)) and the 
LSR isn't as full as it could be either. Part of the problem is that 
these things (and the manual, for that matter) require that you already 
know the problem or some of the keywords associated with it. An FAQ or 
wiki can work best when it provides links to the appropriate 
places--just like answers on the mailing list!

> I try to make adding to the existing documentation as easy as possible. 
>  I don't have the time or knowledge to write all the docs myself, but if 
> somebody sends me an email with new stuff, I add it very quickly.  For 
> users, ***adding new material to the docs is easier than writing a faq, 
> webpage, or wiki***.  All you need is an email client, some time, and 
> some knowledge.  I will take care of everything else.

I must say that one of the reasons I enjoy LilyPond is that the 
documentation is so good, and it keeps getting better at an amazing 
rate. Your work in making contributions easy and welcome is a great 
asset to the LilyPond community! (And finding my name on the 2.7 
contributors list was one of the biggest buzzes I've had in a while!)

> I try to monitor the mailing lists for FAQs, but sometimes things slip 
> through.  Especially vocal/lyric issues -- I don't even understand the 
> material that's currently in the docs, so I'm not qualified to write new 
> material about lyrics.  If you see something missing in the 2.7 docs, 
> please tell me what to add and where, and I'll take care of it.
>
>
> If you're concerned about duplication of effort in the manual, just send 
> an email to -devel telling us that you're working on a certain doc 
> section.  If somebody else is working on that, they'll let you know.  If 
> nobody is -- and that's almost certainly the case -- then you can go 
> ahead and write stuff.
You're right again--duplication of effort rarely seems to be a problem. 
I'm probably more worried about duplication of effort in lilypond-user.

> > 3) would there be enough interest from the LilyPond-guru community to 
> > contribute and maintain? I'm happy to make a start, but it would be 
> > better if it were a shared effort.
>
> As far as I know, the Lilypond wiki that people started up about six 
> months ago is dead.  Does that answer the question?
Yes, unfortunately. I wonder what the answer there is, without making 
work for anyone but those interested. Part of the problem must be 
marketing--as I said, I didn't know it existed. But wikis have a way of 
growing rapidly, then dying as the enthusiasm of the founder moves on to 
something else.

As it turns out (as another respondent to this thread advises) there is 
already a LilyPond FAQ at http://lilypond.org/web/about/faq I didn't 
know that existed either--it's buried two links deep on the site.

This leads me back to the earlier point (which I know has been discussed 
on -devel recently): the information is out there, it just seems to be a 
little difficult to find at first. To this I have no answers that 
haven't already been tried.

So my question about starting an FAQ can now be safely forgotten. There 
seem to be plenty of places to direct my efforts, and so, thusly, I will!

--Cam