[EMAIL PROTECTED] writes:
First of all I agree that add work for the maintainer of lilypond is in the long run a very bad idea.
Making Hans fiddle with the docs means less improvement to the program that said.
There are many levels to improving the docs. Some issues are infact really bugs: The doc says do x but it does acheive the results stated.
Then there are other issues:
Is that particular item understandable?
What about the structure of that entry, maybe it could be more understandable if written differently.
There is also the issue of making a cleaner seperation between the hacking issues and the more straight forward howto issues.
I have often clicked a link to find more about a subject instead of infact finding more about that subject I find scheme stuff.
this is intentional, but I can understand that it is confusing.
I've updated the tremolo entry of the manual with links. I've also changed the SEEALSO section like this
In this manual: *Tremolo subdivisions::, *Note Repeats::.
Internals: tremolo beams are *Beam:: objects. Single stem tremolos are *StemTremolo::s. The music expression is *note TremoloEvent::,
Example files: `input/regression/chord-tremolo.ly', `input/regression/stem-tremolo.ly'.
now what only needs to be done, is applying the same layout to all other SEEALSO entries.
(hint hint)
Thanks this is now much clearer. What does it take to update this? I would be glad to help if needed.
I feel that the users are the ones who will improve and refine the docs, once a technical solution for including them in the process is found.
I agree with Jan on this one: if the threshold is lowered, then we
will get less useful information. I think that the attitude that needs
change is
Being lazy by nature I can't be sure I would surf to a wiki after]
Not my intention, the writing work etc. is ok by me, going to a wiki makes me become lazy.
(read I don't want to waste my time surfing when I could just make the change myself or write an email which usually gets feedback as opposed to a wiki.)
I guess I just don't like wikis.....
^^^^^ ^^^^
finding problems in the docs.
I am not trying to be vindictive. It's just that writing good
documentation is a lot of work, and almost as difficult as writing
good code. It is not the work for lazy people.
Again the lazyness issue is related to wikis. The lowering of the threshold issue is partially an issue but truthfully the kiss method usually is the best. In my years as a tech writer, the best was expressed as simply and clearly as possible, and with the least amount of words.
My experience with the lilypond docs are that they usually put in the least amount of information as possible, relying on the other sections of the documentation to fill in the missing pieces. This is in fact how programmers think, regular users will skip to the help they need as in F1 help and can get confused.
That said the docs are infact of a high quality and I am not intending any critisisim of them, rather my comments are meant to make lilypond approachable by the sibelius/finale people who the mere mention of a text based notation system makes their eyes roll in the heads.
I hope that by highlighting these issues my composer arranger friend who said that he will never use a text based system will one day try it and be hooked on it like I am.
If that means lowering the threshold so be it. Sometimes it isn't so much the information but how it is presented that makes it useful.
Sorry if I a belaboring the point
Aaron
It's the same as with getting patches included: if you want
to have something, you have to invest some effort to get it.
_______________________________________________ Lilypond-user mailing list [EMAIL PROTECTED] http://mail.gnu.org/mailman/listinfo/lilypond-user