Re: How do new users feel about LilyPond's documentation?

[Kieren MacMillan]

Hi Andrew,

> I started using Lily for serious maybe a month ago, so I'm what you'd call 
> new.

Welcome!  =)

> There's been a lot of mention (I imagine rightfully) about how Lily is 
> capable, above all, of making beautifully engraved scores, and her 
> suitability to managing a text-based, distributed, and version/change-tracked 
> workflow. All of that sounds awesome, but I don't see anywhere where that's 
> comprehensively documented. 

Part of the problem is that much of that is still in flux — definitely at too 
early a stage to spend much time documenting (since it’s all likely to change). 
We chat about the stylesheet system, but there isn’t even a defined mechanism 
yet. I rave about the edition-engraver, but its use and implementation changes 
regularly enough (and we’re still figuring out what it can and should do, and 
how), so developing “comprehensive documentation” would be foolish.

> what I'm really looking for is a comprehensive "best practices" style guide 
> for how to organize larger scores […]
> Urs, I think this would probably dovetail nicely with your efforts to build a 
> pool of competent engravers, as we would then all be working from the same 
> style guidelines

And would also feed into any templates (as opposed to stylesheets) that 
openLilyLib puts forth. (Again, once real templates are in place, a lot of 
these “how do I” questions will be answered for beginning users. However, 
having a template to use doesn’t in any way give a user the knowledge of how to 
do it themselves, or why it was or should be done that way; that’s where 
documentation comes in.)

I would be happy to help write a “Best Practices” guide (with whatever small 
free time I currently have), if only we as a community could agree on what that 
document would look like, where it would live, and what it would contain. Is it 
an 11th manual to add to the collection found at 
<http://www.lilypond.org/website/manuals.html>? That seems the likeliest 
candidate for my money.

Best,
Kieren.
________________________________

Kieren MacMillan, composer
‣ website: www.kierenmacmillan.info
‣ email: address@hidden