Re: More documentation

[Graham Percival]

On Thu, 22 May 2003 19:48:53 +0200
Mats Bengtsson <address@hidden> wrote:
> > I have two ideas for new documentations:
> > 1)  a FAQ that's really just a bunch of saved emails from lilypond-user.
>
> 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.

I always knew that it existed, but I never realized quite how easy it was
to add stuff to it.  wiki is perfect for what I had in mind.

http://lilypond.org/wiki/?MailingLists

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

What a pity that they're so dedicated.  :)

In all seriousness, I don't think that keeping wiki up-to-date should be
a problem once people realize how easy it is.  It's the perfect job for
somebody who wants to help but doesn't have much technical knowledge
(like me).  If you're an "end-user" rather than a programmer, texinfo
looks a bit scary, and if something fails during a "make web-doc", you
can feel lost.  That discourages newbies from contributing to the tutorial
and manual.  But there's no technical difficulties in dealing with wiki...

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

I'll take over the Wiki pages, unless somebody who knows even less than
me wants to do it.

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

Yes.  I think we should emphasize them even more in the restructured
documents.

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

Good idea.

Cheers,
- Graham