How do new users feel about LilyPond's documentation?

classic Classic list List threaded Threaded
48 messages Options
123
Reply | Threaded
Open this post in threaded view
|

How do new users feel about LilyPond's documentation?

tisimst
All,

I've been thinking about this a lot lately, even going so far as to create my own "Quick Start" tutorials for new users, but I can only go so far in my own head. I really have two questions that I keep wondering about:
  1. What is the thing you (especially new users) like the least about LilyPond's documentation structure?
  2. If you could have the same documentation structure as found in another notation program, which program is it? Or put another way: Is there a notation program out there that has a documentation structure you like?
I'm asking this because I'm trying to determine how we in the 'Pond can make it easier for new users to jump in with both feet instead of dipping a toe and getting scared of the deep.

I may be over-thinking this, but I keep getting the feeling that people are scared of using LilyPond partially because the documentation, though deep and detailed, is a little too deep and technical for new users who are familiar with a GUI program and less familiar with programming.

Any thoughts? I think I'm mostly interested in comments related to the *Learning* and *Notation* manuals, but comments about the others are welcome, too.

I can't say that I'm proposing any massive changes to the documentation, but I'd like to know if there's something else that would be more new user-friendly.

- Abraham

_______________________________________________
lilypond-user mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-user
Reply | Threaded
Open this post in threaded view
|

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

Flaming Hakama by Elaine

> What is the thing you (especially new users) like the least about LilyPond's documentation structure?

Insufficient explanation of the object model, the process model and the hierarchy of languages used and how they fit together.  Example:  Does anyone here really understand what a "voice" actually is?  How about an "engraver"?   (If so, I have many follow-up questions for you...)

At the root of the problem is that the documentation allows you to think that lilypond is a program to organize music.  When it is really a program to organize grobs.

_______________________________________________
lilypond-user mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-user
Reply | Threaded
Open this post in threaded view
|

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

Federico Bruni
In reply to this post by tisimst
Hi Abraham

I've been using LilyPond since 6 years.
I think that LilyPond documentation is great. Learning Manual is a gentle introduction (basically 3 chapters only) for new users and Notation Reference is a complete reference, well indexed and easy to search through.
I never found anything better (which is as complex as LilyPond).

2015-04-22 17:09 GMT+02:00 Abraham Lee <[hidden email]>:
All,

I've been thinking about this a lot lately, even going so far as to create my own "Quick Start" tutorials for new users, but I can only go so far in my own head. I really have two questions that I keep wondering about:
  1. What is the thing you (especially new users) like the least about LilyPond's documentation structure?
  2. If you could have the same documentation structure as found in another notation program, which program is it? Or put another way: Is there a notation program out there that has a documentation structure you like?

1. The missing connection between input and output, in other words something similar to the experience of point-and-click in an editor. Yes, this is not about structure. I think that structure of NR is Ok.
Also, syntax highlighting would help readability:
https://code.google.com/p/lilypond/issues/detail?id=2578
https://code.google.com/p/lilypond/issues/detail?id=1005

2. no idea
 
I'm asking this because I'm trying to determine how we in the 'Pond can make it easier for new users to jump in with both feet instead of dipping a toe and getting scared of the deep.

I may be over-thinking this, but I keep getting the feeling that people are scared of using LilyPond partially because the documentation, though deep and detailed, is a little too deep and technical for new users who are familiar with a GUI program and less familiar with programming.


I think that the best way for that kind of users is starting from screencasts:
http://benlemon.me/blog/music/lilypond/operation-lilypond

What I would find useful is an interactive guide to lilypond syntax:
https://code.google.com/p/lilypond/issues/detail?id=4200


_______________________________________________
lilypond-user mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-user
Reply | Threaded
Open this post in threaded view
|

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

tisimst
On Wed, Apr 22, 2015 at 12:48 PM, Federico Bruni [via Lilypond] <[hidden email]> wrote:

What I would find useful is an interactive guide to lilypond syntax:
https://code.google.com/p/lilypond/issues/detail?id=4200


I totally agree! How about some collaboration with Trevor Dixon's lilybin.com? I use it all the time and I get the sense there are others who do, too. It provides quick access to the latest stable and unstable versions right in a web browser.

- Abraham
Reply | Threaded
Open this post in threaded view
|

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

Urs Liska
In reply to this post by Federico Bruni


Am 22.04.2015 um 20:48 schrieb Federico Bruni:
Hi Abraham

I've been using LilyPond since 6 years.
I think that LilyPond documentation is great. Learning Manual is a gentle introduction (basically 3 chapters only) for new users and Notation Reference is a complete reference, well indexed and easy to search through.
I never found anything better (which is as complex as LilyPond).

I am quite in line with that impression. I don't think the *documentation* can be *much* better in general. However, there are a few things that would help new users (I think it would be very good if some of these could also comment on this thread).

It would be helpful if there were more learning material that has a slower pace and into more depth at explaining things than the notation reference. The Learning Manual is very good, but when that's finished people are not ready to walk alone.
That's what I intend with the tutorials section on the blog, but of course these posts are only drops in the ocean. But better than nothing.
I could also see something like a community book emerging from these tutorials, but I'm not sure how well this would work out.

Urs


2015-04-22 17:09 GMT+02:00 Abraham Lee <[hidden email]>:
All,

I've been thinking about this a lot lately, even going so far as to create my own "Quick Start" tutorials for new users, but I can only go so far in my own head. I really have two questions that I keep wondering about:
  1. What is the thing you (especially new users) like the least about LilyPond's documentation structure?
  2. If you could have the same documentation structure as found in another notation program, which program is it? Or put another way: Is there a notation program out there that has a documentation structure you like?

1. The missing connection between input and output, in other words something similar to the experience of point-and-click in an editor. Yes, this is not about structure. I think that structure of NR is Ok.
Also, syntax highlighting would help readability:
https://code.google.com/p/lilypond/issues/detail?id=2578
https://code.google.com/p/lilypond/issues/detail?id=1005

2. no idea
 

I'm asking this because I'm trying to determine how we in the 'Pond can make it easier for new users to jump in with both feet instead of dipping a toe and getting scared of the deep.

I may be over-thinking this, but I keep getting the feeling that people are scared of using LilyPond partially because the documentation, though deep and detailed, is a little too deep and technical for new users who are familiar with a GUI program and less familiar with programming.


I think that the best way for that kind of users is starting from screencasts:
http://benlemon.me/blog/music/lilypond/operation-lilypond

What I would find useful is an interactive guide to lilypond syntax:
https://code.google.com/p/lilypond/issues/detail?id=4200



_______________________________________________
lilypond-user mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-user


_______________________________________________
lilypond-user mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-user
Reply | Threaded
Open this post in threaded view
|

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

N. Andrew Walsh
I started using Lily for serious maybe a month ago, so I'm what you'd call new. I find the guide far more useful than the manual (the former seems more structured around how to do specific things, while the latter seems much more a general conceptual introduction). 

However (and this is something I mentioned on a couple recent message exchanges), I feel that neither one of them gets me very far past making a single monolithic file using defaults. 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. 

Let's take my case: I'm transcribing masses from some obscure composer from the 18th century. There are no extant scores, only the parts (which ironically works better for Lily's structure). I want these scores to look their absolute best, and the underlying files to follow the best practices for structure and organization. I want to put the score and parts alongside the work of a commercial (read: Sibelius-using) house and have it be unambiguously a better-looking and standards-conforming result, and be able to show the incredible flexibility and rigorous flow-control that using the underlying system can offer.

I don't see anywhere in the reference or the manual where that sort of comprehensive style guide is presented. I'm thinking something like the doorstops O'Reilly's uses for documenting, say, HTML. I hate to use the term (it's already been ruined by bureaucrats), but 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. 

But that's just my use-case. Maybe there are others?

Cheers,

A

On Wed, Apr 22, 2015 at 9:03 PM, Urs Liska <[hidden email]> wrote:


Am 22.04.2015 um 20:48 schrieb Federico Bruni:
Hi Abraham

I've been using LilyPond since 6 years.
I think that LilyPond documentation is great. Learning Manual is a gentle introduction (basically 3 chapters only) for new users and Notation Reference is a complete reference, well indexed and easy to search through.
I never found anything better (which is as complex as LilyPond).

I am quite in line with that impression. I don't think the *documentation* can be *much* better in general. However, there are a few things that would help new users (I think it would be very good if some of these could also comment on this thread).

It would be helpful if there were more learning material that has a slower pace and into more depth at explaining things than the notation reference. The Learning Manual is very good, but when that's finished people are not ready to walk alone.
That's what I intend with the tutorials section on the blog, but of course these posts are only drops in the ocean. But better than nothing.
I could also see something like a community book emerging from these tutorials, but I'm not sure how well this would work out.

Urs


2015-04-22 17:09 GMT+02:00 Abraham Lee <[hidden email]>:
All,

I've been thinking about this a lot lately, even going so far as to create my own "Quick Start" tutorials for new users, but I can only go so far in my own head. I really have two questions that I keep wondering about:
  1. What is the thing you (especially new users) like the least about LilyPond's documentation structure?
  2. If you could have the same documentation structure as found in another notation program, which program is it? Or put another way: Is there a notation program out there that has a documentation structure you like?

1. The missing connection between input and output, in other words something similar to the experience of point-and-click in an editor. Yes, this is not about structure. I think that structure of NR is Ok.
Also, syntax highlighting would help readability:
https://code.google.com/p/lilypond/issues/detail?id=2578
https://code.google.com/p/lilypond/issues/detail?id=1005

2. no idea
 

I'm asking this because I'm trying to determine how we in the 'Pond can make it easier for new users to jump in with both feet instead of dipping a toe and getting scared of the deep.

I may be over-thinking this, but I keep getting the feeling that people are scared of using LilyPond partially because the documentation, though deep and detailed, is a little too deep and technical for new users who are familiar with a GUI program and less familiar with programming.


I think that the best way for that kind of users is starting from screencasts:
http://benlemon.me/blog/music/lilypond/operation-lilypond

What I would find useful is an interactive guide to lilypond syntax:
https://code.google.com/p/lilypond/issues/detail?id=4200



_______________________________________________
lilypond-user mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-user


_______________________________________________
lilypond-user mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-user



_______________________________________________
lilypond-user mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-user
Reply | Threaded
Open this post in threaded view
|

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

Gilles Sadowski
Hello.

On Wed, 22 Apr 2015 21:19:12 +0200, N. Andrew Walsh wrote:

> I started using Lily for serious maybe a month ago, so I'm what you'd
> call
> new. I find the guide far more useful than the manual (the former
> seems
> more structured around how to do specific things, while the latter
> seems
> much more a general conceptual introduction).
>
> However (and this is something I mentioned on a couple recent message
> exchanges), I feel that neither one of them gets me very far past
> making a
> single monolithic file using defaults. 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.
>
> Let's take my case: I'm transcribing masses from some obscure
> composer from
> the 18th century. There are no extant scores, only the parts (which
> ironically works better for Lily's structure). I want these scores to
> look
> their absolute best, and the underlying files to follow the best
> practices
> for structure and organization. I want to put the score and parts
> alongside
> the work of a commercial (read: Sibelius-using) house and have it be
> unambiguously a better-looking and standards-conforming result, and
> be able
> to show the incredible flexibility and rigorous flow-control that
> using the
> underlying system can offer.
>
> I don't see anywhere in the reference or the manual where that sort
> of
> comprehensive style guide is presented. I'm thinking something like
> the
> doorstops O'Reilly's uses for documenting, say, HTML. I hate to use
> the
> term (it's already been ruined by bureaucrats), but what I'm really
> looking
> for is a comprehensive "best practices" style guide for how to
> organize
> larger scores.

Best practices, yes; for any score (not just large ones).[1]
A flexible structure that would be "compelling" and foster the creation
of
"compliant" tools.

Is it GridLY? [Cf. other post.]

Regards,
Gilles

>
> 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.
>
> But that's just my use-case. Maybe there are others?
>
> Cheers,
>
> A
>
> On Wed, Apr 22, 2015 at 9:03 PM, Urs Liska <[hidden email]>
> wrote:
>
>>
>>
>> Am 22.04.2015 um 20:48 schrieb Federico Bruni:
>>
>> Hi Abraham
>>
>>  I've been using LilyPond since 6 years.
>>  I think that LilyPond documentation is great. Learning Manual is a
>> gentle introduction (basically 3 chapters only) for new users and
>> Notation
>> Reference is a complete reference, well indexed and easy to search
>> through.
>>  I never found anything better (which is as complex as LilyPond).
>>
>>
>> I am quite in line with that impression. I don't think the
>> *documentation*
>> can be *much* better in general. However, there are a few things
>> that would
>> help new users (I think it would be very good if some of these could
>> also
>> comment on this thread).
>>
>> It would be helpful if there were more learning material that has a
>> slower
>> pace and into more depth at explaining things than the notation
>> reference.
>> The Learning Manual is very good, but when that's finished people
>> are not
>> ready to walk alone.
>> That's what I intend with the tutorials section on the blog, but of
>> course
>> these posts are only drops in the ocean. But better than nothing.
>> I could also see something like a community book emerging from these
>> tutorials, but I'm not sure how well this would work out.
>>
>> Urs
>>
>>
>> 2015-04-22 17:09 GMT+02:00 Abraham Lee <[hidden email]>:
>>
>>> All,
>>>
>>>  I've been thinking about this a lot lately, even going so far as
>>> to
>>> create my own "Quick Start" tutorials for new users, but I can only
>>> go so
>>> far in my own head. I really have two questions that I keep
>>> wondering about:
>>>
>>>    1. What is the thing you (especially new users) like the least
>>> about
>>>    LilyPond's documentation structure?
>>>    2. If you could have the same documentation structure as found
>>> in
>>>    another notation program, which program is it? Or put another
>>> way: Is there
>>>    a notation program out there that has a documentation structure
>>> you like?
>>>
>>>
>>  1. The missing connection between input and output, in other words
>> something similar to the experience of point-and-click in an editor.
>> Yes,
>> this is not about structure. I think that structure of NR is Ok.
>> Also, syntax highlighting would help readability:
>> https://code.google.com/p/lilypond/issues/detail?id=2578
>> https://code.google.com/p/lilypond/issues/detail?id=1005
>>
>>  2. no idea
>>
>>
>>>
>>>    1.
>>>
>>>  I'm asking this because I'm trying to determine how we in the
>>> 'Pond can
>>> make it easier for new users to jump in with both feet instead of
>>> dipping a
>>> toe and getting scared of the deep.
>>>
>>>  I may be over-thinking this, but I keep getting the feeling that
>>> people
>>> are scared of using LilyPond partially because the documentation,
>>> though
>>> deep and detailed, is a little too deep and technical for new users
>>> who are
>>> familiar with a GUI program and less familiar with programming.
>>>
>>>
>>  I think that the best way for that kind of users is starting from
>> screencasts:
>> http://benlemon.me/blog/music/lilypond/operation-lilypond
>>
>>  What I would find useful is an interactive guide to lilypond
>> syntax:
>> https://code.google.com/p/lilypond/issues/detail?id=4200
>>
>>
>>
>> _______________________________________________
>> lilypond-user mailing
>> [hidden email]://lists.gnu.org/mailman/listinfo/lilypond-user
>>
>>
>>
>> _______________________________________________
>> lilypond-user mailing list
>> [hidden email]
>> https://lists.gnu.org/mailman/listinfo/lilypond-user
>>
>>


_______________________________________________
lilypond-user mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-user
Reply | Threaded
Open this post in threaded view
|

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

Larry Kent-2
In reply to this post by tisimst
My problem is that too much of it is written like the following response from Elaine, which looks like Pprogrammers Only Need Apply. 

I get frustrated when I'm looking for something to answer the question "How do I increase/decrease the space between the bottom system and the footer?" ...and cannot find an answer that begins "Here's how to increase/decrease the space between the bottom system and the footer."

If Lilypond such a complex program that I should not expect it to meet me at the intersection I just described?

Thanks,
Larry Kent
Tampa, FL


On Wed, Apr 22, 2015 at 2:11 PM, Flaming Hakama by Elaine <[hidden email]> wrote:

> What is the thing you (especially new users) like the least about LilyPond's documentation structure?

Insufficient explanation of the object model, the process model and the hierarchy of languages used and how they fit together.  Example:  Does anyone here really understand what a "voice" actually is?  How about an "engraver"?   (If so, I have many follow-up questions for you...)

At the root of the problem is that the documentation allows you to think that lilypond is a program to organize music.  When it is really a program to organize grobs.




_______________________________________________
lilypond-user mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-user
Reply | Threaded
Open this post in threaded view
|

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

tisimst
Larry,

On Wed, Apr 22, 2015 at 1:43 PM, Larry Kent-2 [via Lilypond] <[hidden email]> wrote:
My problem is that too much of it is written like the following response from Elaine, which looks like Pprogrammers Only Need Apply. 

I get frustrated when I'm looking for something to answer the question "How do I ..."

This is exactly why I posed the questions. I keep feeling like it would be super helpful to have a section (in or out of the official docs) that uses verbiage like this. Not sure what that would look like and what the restrictions would be for choosing to put content there or not. Either way, having something that is sooooo obvious (with as few clicks as possible) to describe how to do many of the most common tasks seems like a useful thing for new users. Some examples:

"How do I change the input language to English?"
"How do I add a slur?" 
"How do I adjust the page margins?"
"How do I add another voice?"
"How do I change the tempo?"
"How do I add an articulation?"
"How do I add an instrument?"
"How do I change the size of a staff?"
"How do I group instruments together?"
"How do I import a MusicXML file?"
"How do I change the angle of a beam?"
"How do I create a tuplet?"
"How do I add the closing barline?"
etc.

I think the questions need to be oriented to the language that GUI users are used to using (like "How do I add an instrument?", even though LilyPond doesn't deal with instruments in the same way as the GUI programs). This should provide a good transition to understanding more how LilyPond thinks about (and expects) the input syntax.

Just thinking out loud...

- Abraham
Reply | Threaded
Open this post in threaded view
|

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

Urs Liska


Am 22.04.2015 um 22:05 schrieb tisimst:
Larry,

On Wed, Apr 22, 2015 at 1:43 PM, Larry Kent-2 [via Lilypond] <[hidden email]> wrote:
My problem is that too much of it is written like the following response from Elaine, which looks like Pprogrammers Only Need Apply. 

I get frustrated when I'm looking for something to answer the question "How do I ..."

This is exactly why I posed the questions. I keep feeling like it would be super helpful to have a section (in or out of the official docs) that uses verbiage like this. Not sure what that would look like and what the restrictions would be for choosing to put content there or not. Either way, having something that is sooooo obvious (with as few clicks as possible) to describe how to do many of the most common tasks seems like a useful thing for new users. Some examples:

"How do I change the input language to English?"
"How do I add a slur?" 
"How do I adjust the page margins?"
"How do I add another voice?"
"How do I change the tempo?"
"How do I add an articulation?"
"How do I add an instrument?"
"How do I change the size of a staff?"
"How do I group instruments together?"
"How do I import a MusicXML file?"
"How do I change the angle of a beam?"
"How do I create a tuplet?"
"How do I add the closing barline?"
etc.

I think the questions need to be oriented to the language that GUI users are used to using (like "How do I add an instrument?", even though LilyPond doesn't deal with instruments in the same way as the GUI programs). This should provide a good transition to understanding more how LilyPond thinks about (and expects) the input syntax.

Just thinking out loud...

This is exactly what we intended with the "tutorials" category on Scores of Beauty (http://lilypondblog.org/category/using-lilypond/tutorials/). As it stands also these are too much oriented towards the more complicated matters - but thsi is also due to lack of external input.
I've said several times (although it could probably be repeated more often) that I'd be happy if everybody who learns something (like the above issues) through help on the mailing lists would read a short tutorial post about it we would get a nice collection of FAQs.

I still think this would be a worthwile effort if we'd have more people contributing to that. If we were to have more content it would be a viable approach to create a website around it, something like a commented index pointing to the posts. And, it would be possible to sketch that "book".

Urs


- Abraham


View this message in context: Re: How do new users feel about LilyPond's documentation?
Sent from the User mailing list archive at Nabble.com.


_______________________________________________
lilypond-user mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-user


_______________________________________________
lilypond-user mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-user
Reply | Threaded
Open this post in threaded view
|

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

m.tarenskeen
In reply to this post by Larry Kent-2


On Wed, 22 Apr 2015, Larry Kent wrote:

> I get frustrated when I'm looking for something to answer the question "How do I increase/decrease the space between the bottom system and the
> footer?" ...and cannot find an answer that begins "Here's how to increase/decrease the space between the bottom system and the footer."

> At the root of the problem is that the documentation allows you to think that lilypond is a program to organize music.  When it is really a
> program to organize grobs.


I have been using LilyPond for some time now but still have problems
finding and understanding the subject of tweaking and changing defaults.
Yes, the info is all there in the manuals. And with the help of the kind
and helpful people in this mailinglist I have always been able to solve
any problem I encountered.

Stiil, I will try to give a sketch what happens to me again and again:

I want to learn about how to change defaults and how to tweak default
output so I open the Notation Reference:

Notation Refence -> 5. Changing Defaults
" A tutorial introduction to accessing and modifying these properties can
be found in the Learning Manual, see Tweaking output. This should be read
first " -->

Learning Manual -> 4. Tweaking Output -> 4.1 Tweaking Basics
->4.1.1 Introduction to tweaks

"Before starting on this Chapter you may wish to review the section
Contexts and engravers, as Contexts, Engravers, and the Properties
contained within them are fundamental to understanding and constructing
Tweaks." -->

LM 3.3 Contexts and Engravers -> 3.3.1 Contexts explained -->
also see NR 5.1.1 Contexts explained -->

etc etc

The end of the story is: I have read a lot of interesting stuff and learnt
a lot, but still don't know how to make a particular tweak or change some
default setting. Fortunately I can very often find answers to my questions
in the snippets repository, or in the mailinglist archives.

--

MT
_______________________________________________
lilypond-user mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-user
Reply | Threaded
Open this post in threaded view
|

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

Wols Lists
In reply to this post by N. Andrew Walsh
On 22/04/15 20:19, N. Andrew Walsh wrote:
> I don't see anywhere in the reference or the manual where that sort of
> comprehensive style guide is presented. I'm thinking something like the
> doorstops O'Reilly's uses for documenting, say, HTML. I hate to use the
> term (it's already been ruined by bureaucrats), but what I'm really
> looking for is a comprehensive "best practices" style guide for how to
> organize larger scores.

What I'd like to see is worked, documented examples. The lsr is great is
some respects, but I do a load of band parts. A complete PD part (Sousa
is, I believe, PD, Kenneth Alford died in 1945 so at the end of this
year his work falls out of the 70 year rule ...) would be great, and
showcase a lot of useful techniques.

I also keep seeing a lot of stuff about "separating notes from layout".
I try to do that, but again, a documented example would be great. My big
involvement with lilypond when I was learning was the 2.4/2.6 era so my
style is stuck in that era - I think things have changed a lot since
then so a documented example would be great ...

Cheers,
Wol

_______________________________________________
lilypond-user mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-user
Reply | Threaded
Open this post in threaded view
|

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

Carl Sorensen-3
In reply to this post by m.tarenskeen


On 4/22/15 1:30 PM, "Martin Tarenskeen" <[hidden email]> wrote:

>Stiil, I will try to give a sketch what happens to me again and again:
>
>I want to learn about how to change defaults and how to tweak default
>output so I open the Notation Reference:
>
>Notation Refence -> 5. Changing Defaults
>" A tutorial introduction to accessing and modifying these properties can
>be found in the Learning Manual, see Tweaking output. This should be read
>first " -->

I think this appropriate for a reference manual.  It should point you to a
tutorial, if you need the tutorial.

>
>Learning Manual -> 4. Tweaking Output -> 4.1 Tweaking Basics
>->4.1.1 Introduction to tweaks
>
>"Before starting on this Chapter you may wish to review the section
>Contexts and engravers, as Contexts, Engravers, and the Properties
>contained within them are fundamental to understanding and constructing
>Tweaks." -->

This is a potentially bigger problem, because the Learning Manual is not
intended to be a reference manual.  But it *is* intended to be read
sequentially.  Maybe we should leave this particular paragraph out, or
change it to read "If you have trouble understanding this section of the
manual, you may wish to review Contexts and Engravers."  That way, you're
providing some help, but not asking the reader to go there directly.

>The end of the story is: I have read a lot of interesting stuff and learnt
>a lot, but still don't know how to make a particular tweak or change some
>default setting.

If the manual were to show you exactly how to make every possible
particular tweak or change every possible default setting, it would need
to be many times longer than it is.  The goal is to help you understand
how to use the manual to find your specific tweak.

I'm sure there is much that can be done to improve the situation, but I
don't think it is to develop an exhaustive list of "How do I change X?"

Thanks,

Carl


_______________________________________________
lilypond-user mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-user
Reply | Threaded
Open this post in threaded view
|

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

Simon Albrecht-2
Am 22.04.2015 um 23:19 schrieb Carl Sorensen:

>
> On 4/22/15 1:30 PM, "Martin Tarenskeen" <[hidden email]> wrote:
>
>> Stiil, I will try to give a sketch what happens to me again and again:
>>
>> I want to learn about how to change defaults and how to tweak default
>> output so I open the Notation Reference:
>>
>> Notation Refence -> 5. Changing Defaults
>> " A tutorial introduction to accessing and modifying these properties can
>> be found in the Learning Manual, see Tweaking output. This should be read
>> first " -->
> I think this appropriate for a reference manual.  It should point you to a
> tutorial, if you need the tutorial.
>
>> Learning Manual -> 4. Tweaking Output -> 4.1 Tweaking Basics
>> ->4.1.1 Introduction to tweaks
>>
>> "Before starting on this Chapter you may wish to review the section
>> Contexts and engravers, as Contexts, Engravers, and the Properties
>> contained within them are fundamental to understanding and constructing
>> Tweaks." -->
> This is a potentially bigger problem, because the Learning Manual is not
> intended to be a reference manual.  But it *is* intended to be read
> sequentially.
I think this is an important point: the manual need to be used the way
they should. Often, problems arise because people just start trying lily
out (as they use to start working with a WYSIWYG tool, probably) and
don’t first get acquainted with the fundamentals – laid out pretty well
in the LM.
Perhaps it boils down to this: Using a conventional typesetting software
may be learned through trial and error, using lilypond can’t. You have
to be willing to get a grip of it from the basic, and for me this
involved to delve into a completely new way of thinking. The reason I
did that (investing a maybe unreasonable amount of time over years) was
because I like doing things properly unto perfection, and this is
probably something I share with many Lilypond users. So everybody who
likes a more casual, superficial, easy-to-use approach will probably
always be in need of a powerful front-end (Denemo, perhaps future
extended Frescobaldi, stylesheets, code templates etc.), or prefer to
stay with Finale or Sibelius (or worse, Capella, etc.) default output,
no matter how ugly it be.
But developing those front-ends should be somewhat separate from actual
Lilypond core development, shouldn’t it?
And oops, this post landed inbetween the two large threads currently
going on… :-)

Yours, Simon

_______________________________________________
lilypond-user mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-user
Reply | Threaded
Open this post in threaded view
|

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

Simon Albrecht-2
In reply to this post by tisimst
Hello,

I recall that I was always thinking it would be best to have a person at hand, maybe even sharing a ‘bureau’, who could answer my question. Or attending a class, in which one would for example be guided in coding example scores, and receive immediate feedback. Later I realised that I might have saved much time asking on the ly-user list, of which I somehow only got wind after some time. But these wishes are of course far from reality: we may only dream of a future in which every university music student or even pupils at music schools would be taught basics of lilypond as a standard tool, similar perhaps to the use of LaTeX in maths and physics…
Anyway, reading together everything on the internet from very extensive resources has been really cumbersome, especially as I hadn’t done it before or known the way to do this.
Now that’s only a report of my experience. I’d have to make some thorough thoughts on how this might have been eased.

Yours, Simon

PS. But in the course of years, I got the grip and now I get along pretty well :-) Though, it’s a never-ending way, if one goes on delving into scheme and the source and the docs and contributing etc. etc. … But rewarding it is.

Am 22.04.2015 um 17:09 schrieb Abraham Lee:
All,

I've been thinking about this a lot lately, even going so far as to create my own "Quick Start" tutorials for new users, but I can only go so far in my own head. I really have two questions that I keep wondering about:
  1. What is the thing you (especially new users) like the least about LilyPond's documentation structure?
  2. If you could have the same documentation structure as found in another notation program, which program is it? Or put another way: Is there a notation program out there that has a documentation structure you like?
I'm asking this because I'm trying to determine how we in the 'Pond can make it easier for new users to jump in with both feet instead of dipping a toe and getting scared of the deep.

I may be over-thinking this, but I keep getting the feeling that people are scared of using LilyPond partially because the documentation, though deep and detailed, is a little too deep and technical for new users who are familiar with a GUI program and less familiar with programming.

Any thoughts? I think I'm mostly interested in comments related to the *Learning* and *Notation* manuals, but comments about the others are welcome, too.

I can't say that I'm proposing any massive changes to the documentation, but I'd like to know if there's something else that would be more new user-friendly.

- Abraham


_______________________________________________
lilypond-user mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-user


_______________________________________________
lilypond-user mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-user
Reply | Threaded
Open this post in threaded view
|

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

Kieren MacMillan
In reply to this post by Wols Lists
Hi Wol,

> What I'd like to see is worked, documented examples.

I’m happy to supply a few… But there are so many questions:

1. Where would they be kept?

2. How “rich” would the examples need to be, or not be? Even just a one-page excerpt from my Passacaglia for String Quartet would require something on the order of 20 separate files (stylesheets, general tweaks and functions, etc.), which I think would be off-putting for someone just starting out.

3. How would questions of style (e.g., I am now a total crusader against \relative mode) be resolved?

etc. etc. etc.

If this is to be part of the official documentation, I imagine it will be even more difficult getting something like that approved than a code patch (which has fairly rigorous “black-and-white” rules), which as you may know is notoriously difficult to get approved.

> I also keep seeing a lot of stuff about "separating notes from layout".
> I try to do that, but again, a documented example would be great.

Again, happy to do it… once the questions are answered satisfactorily.

Best,
Kieren.
________________________________

Kieren MacMillan, composer
‣ website: www.kierenmacmillan.info
‣ email: [hidden email]


_______________________________________________
lilypond-user mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-user
Reply | Threaded
Open this post in threaded view
|

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

Carl Sorensen-3
In reply to this post by Carl Sorensen-3


On 4/22/15 4:13 PM, "Eyolf Østrem" <[hidden email]> wrote:

>On 22.04.2015 (21:19), Carl Sorensen wrote:
>
>> If the manual were to show you exactly how to make every possible
>> particular tweak or change every possible default setting, it would need
>> to be many times longer than it is.  The goal is to help you understand
>> how to use the manual to find your specific tweak.
>>
>> I'm sure there is much that can be done to improve the situation, but I
>> don't think it is to develop an exhaustive list of "How do I change X?"
>
>I tend to disagree. For two reasons:
>
>1. The list (if not necessarily THAT exact list, but a list according to
>the principles lined out) would actually be quite useful, especially in
>the area of tweaking defaults.

The internals reference lists 136 different contexts, and about 200
tunable context properties.  Each context will have (by default) multiple
context proerties.

There are 139 layout objects.  There are 136 object interfaces.  I haven't
counted them, but it looks like there are about 200 properties.  Each
object has multiple interfaces; each interface has multiple properties.
All of the properties and interfaces are candidates for tweaking.

All of this means there are way more than 1,000 questions of the form "How
do I change X?"  (I think I could make a logically consistent argument for
10,000).
Once the list gets long enough, it's hard enough to search through that
you won't do it -- you'll just ask on the list.

That being said, I've found myself using StackExchange to help me do stuff
I can't remember how to do in LaTeX, so maybe it's worth setting up a
LilyPond StackExchange.

>I've been using LP for ten years now, and I still have to spend
>some time in the manual every time I want to do ANYTHING related to
>spacing or changing defaults. The reason for this may be that in these
>areas in particular the underlying language of LP simply isn't good
>enough. You shouldn't have to write scheme code just to add some vertical
>space.

I don't believe you do have to write Scheme code just to add some vertical
space.

But you do need to understand how the vertical spacing algorithm works, at
least at some level.  The complex vertical spacing algorithm is what gives
LilyPond the ability to be tweaked at a very fine level.  I don't think it
should be eliminated.

But I do think that some really nice defaults (like the OpenLilyLib people
are working on) could greatly help the problem by minimizing the need to
do LilyPond adjustments.

Thanks,

Carl




_______________________________________________
lilypond-user mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-user
Reply | Threaded
Open this post in threaded view
|

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

Kieren MacMillan
In reply to this post by Larry Kent-2
Hi Larry,

> I get frustrated when I'm looking for something to answer the question "How do I increase/decrease the space between the bottom system and the footer?" ...and cannot find an answer that begins "Here's how to increase/decrease the space between the bottom system and the footer.”

When I Google “lilypond space footer”, the third hit is <http://www.lilypond.org/doc/v2.19/Documentation/notation/flexible-vertical-spacing-paper-variables>, in which section I find both an example of setting a spacing alist (specifically score-system-spacing) and the description

    last-bottom-spacing
    the distance from the last system or top-level markup on a page to the bottom of the printable area (i.e. the top of the bottom margin)

Now, from there you definitely need to put 2 and 2 together to get 4… which I understand to be the big stumbling block for many new users.

The difficulty is that there is neither time nor space nor contributor interest in developing “full answers” for all of the spacing questions that could possibly be asked — even just addressing the eight spacing items in that section would be overwhelming for both writer and reader.

> If Lilypond such a complex program that I should not expect it to meet me at the intersection I just described?

Yes, unfortunately.

What we *can* do is, like a librarian, tell anyone where to find the books they need to build a deck; what we *can’t* do is provide the design for every conceivable deck configuration that someone might want to build.

Best,
Kieren.

________________________________

Kieren MacMillan, composer
‣ website: www.kierenmacmillan.info
‣ email: [hidden email]


_______________________________________________
lilypond-user mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-user
Reply | Threaded
Open this post in threaded view
|

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

Kieren MacMillan
In reply to this post by Gilles Sadowski
Hi Gilles (et al.),

> Best practices, yes; for any score (not just large ones).[1]
> A flexible structure that would be "compelling" and foster the creation of "compliant" tools.

I have a pretty rich imagination, and I can’t begin to conceive of a Lilypond best practice [singular] or flexible structure [singular] that could possibly satisfy both a newbie who wants to quickly output a 32-bar lead sheet with chord symbols and a power user who wants to manage a crowd-engraved critical edition of “Porgy & Bess”.

Cheers,
Kieren.
________________________________

Kieren MacMillan, composer
‣ website: www.kierenmacmillan.info
‣ email: [hidden email]


_______________________________________________
lilypond-user mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-user
Reply | Threaded
Open this post in threaded view
|

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

Kieren MacMillan
In reply to this post by Carl Sorensen-3
Hi Carl (et al.),

> maybe it's worth setting up a LilyPond StackExchange

Maybe… But we already hear complaints about how “the documentation” is spread across too many sites: the multiple doc books; LSR; the list archives; Scores of Beauty and similar; etc.

> I don't believe you do have to write Scheme code just to add some vertical space.

Correct.

> I do think that some really nice defaults (like the OpenLilyLib people
> are working on) could greatly help the problem
> by minimizing the need to do LilyPond adjustments.

Yes. The introduction of a real stylesheet and template system — with “peer-reviewed” stylesheets and templates — is going to be a serious step forward.

Best,
Kieren.
________________________________

Kieren MacMillan, composer
‣ website: www.kierenmacmillan.info
‣ email: [hidden email]


_______________________________________________
lilypond-user mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-user
123