[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: constructive criticism
From: |
Han-Wen Nienhuys |
Subject: |
Re: constructive criticism |
Date: |
Thu, 8 Jan 2004 12:28:59 +0100 |
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
- Re: emacs editing, was constructive criticism, (continued)
- Re: emacs editing, was constructive criticism, Paul Scott, 2004/01/10
- 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 <=
- Re: constructive criticism, Aaron, 2004/01/08
- 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