Re: constructive criticism

[Aaron]

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