Graham Percival schrieb:
On Thu, Nov 26, 2009 at 10:56:05AM +0100, Marc Hohl wrote:
Well documented code is crucial in such a project for other
developers to jump on the train, so learning by RTF code isn't
fun (as mentioned elsewhere) - for me, it's annoying, it's
frustrating, and it keeps me persistently feeling too stupid
even for the easiest tasks.
Yes, but we can't get well-documented code by waving a magic wand,
nor by asking that anybody spend more time working on lilypond
than they're willing to spend.
When developers use a little bit of their time to describe their work
by adding suitable comments/links to the CG/whatever, things
will slow down for them, but the general situation will improve
considerably. I think we just have to start to bring the problems
due to non-documented code into the people's viewpoint.
So, while the code indentation policy is very strict, why don't
we do something similar concerning the documentation? If only
patches are pushed that are well documented, at least the
improvements will be documented, and perhaps the developer has
some time to document bits and pieces of the code he is
referring to, too.
This sounds quite reasonable.
Then, I miss some general information of the future goals.
I have plans about the non-programming things, which I'll post in
a few days. Unfortunately this doesn't help with the issues
you're asking about.
As I pointed out in my resonse to Han-Wen, it *is* important
to share visions and the underlying philosophy. Writing code
has something to do with aesthetic, so despite of all logical
conclusions, I *feel* when I am on the right track, whether my
code fits into the big picture - or it is just a ugly lump of code
doing its job more or less.
There has been a lot of emotions and some kB of mails in the
last days, so there is a strong will to improve lilypond;
without insulting anyone, I would ask the core developers to try
to see the whole story from somebody's point of view who has no
clue where to start, limited time, but nevertheless the will to
make things better.
And I would ask new contributors to see the whole story from the
point of view of somebody who spent years and year programming
lilypond, explaining concepts to potential contributors only to
have them disappear without writing any code or doc patches, and
who has limited time to work on lilypond.
This is frustrating. With better documentation, however, there
has to be less explanation (I hope), and people can try to find
out how things work without their fear to annoy developers
by asking (in their eyes stupid) questions.
I suggest that the Frogs write down what they know (or think they
know) in the CG -- Ian made a great start with his diagram.
Where can I find this?