[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: constructive criticism
From: |
Aaron |
Subject: |
Re: constructive criticism |
Date: |
Thu, 08 Jan 2004 15:19:14 +0200 |
User-agent: |
Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.6b) Gecko/20031205 Thunderbird/0.4 |
Han-Wen Nienhuys wrote:
address@hidden 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.
- Re: constructive criticism, (continued)
- Re: constructive criticism, Jan Nieuwenhuizen, 2004/01/10
- Re: constructive criticism, Ferenc Wagner, 2004/01/07
- Re: constructive criticism, Aaron, 2004/01/08
- Re: constructive criticism, Mats Bengtsson, 2004/01/08
- Re: constructive criticism, Han-Wen Nienhuys, 2004/01/08
- Re: constructive criticism, Ferenc Wagner, 2004/01/08
- Re: constructive criticism, Nick Busigin, 2004/01/08
- property syntax (was Re: constructive criticism), John Williams, 2004/01/09
- property syntax (was Re: constructive criticism), Han-Wen Nienhuys, 2004/01/10
- Re: constructive criticism, Han-Wen Nienhuys, 2004/01/08
- Re: constructive criticism,
Aaron <=
- Re: constructive criticism, Han-Wen Nienhuys, 2004/01/08
- Re: constructive criticism, Aaron, 2004/01/08
- Re: constructive criticism, Han-Wen Nienhuys, 2004/01/08
- Re: constructive criticism, Aaron, 2004/01/08
- was constructive criticism now tremolo revisited, Aaron, 2004/01/08
- was constructive criticism now tremolo revisited, Han-Wen Nienhuys, 2004/01/08
- Re: constructive criticism, John Williams, 2004/01/08
- Re: constructive criticism, Han-Wen Nienhuys, 2004/01/08
- Re: constructive criticism, Aaron, 2004/01/08
- Re: constructive criticism, Ferenc Wagner, 2004/01/08