Re: constructive criticism

[Han-Wen Nienhuys]

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) 

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

It's the same as with getting patches included: if you want
to have something, you have to invest some effort to get it. 

-- 
 Han-Wen Nienhuys   |   address@hidden   |   http://www.xs4all.nl/~hanwen