Re: More documentation

[Han-Wen Nienhuys]

address@hidden writes:
> Just to clarify, when I said "FAQ", I really meant it in the literal sense
> -- frequently asked questions on lilypond-user.  FAQs often mean documents
> that answer all sorts of questions (and there's nothing wrong with the
> changing definition), but what I imagined was more specific than that.

I think that a FAQ for "normal" how-do-I-do X questions points to
shortcomings in the manual/examples, and should be dealt with by
improving either of those.

> OK, question: what would be most useful for me to do?  As I've mentioned
> previously, I don't have much technical knowledge (of C, scheme, or even
> shell scripts in makefiles).  I'm comfortable editing existing documents
> (such as refman.itely) as long as I don't have many problems building
> the docs.

I think we could use help the most in the website department: we plan
to switch to the new website after 1.8 is out.  Other than that, the
manual might be do with another round of editing once I've finished
with it, and all of the examples in input/ need to be checked for
documentation, current-ness of syntax, and all other things I've
mentioned. Like I said:

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

Probably, the texidoc strings also should have @cindex entries, so we
can make an index for the entire document.

(Let me know when you want to take on any of these tasks, so we can
avoid double work being done) 

> Should I work on the wiki pages?

No. IMO, the wiki has failed, and it makes another tree to the woods
of documentation which is dense enough as it is. We should strive to
make the documentation simpler, that is: more logical structure, and
less different documents (the more documents we have, the harder it is
to figure out where something is documented.)


-- 

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