Re: [frogs] Frog's Lament

[Graham Percival <graham@xxxxxxxxxxxxxxxxx>]

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.

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

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

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.  After
a few weeks, when everybody has discussed+written down everything,
we can ask a more experienced developer to check it over.

This does a few things:
1) it gets more discussion amongst the Frogs
2) it gets Frogs familiar / accustomed to editing the CG
3) we end up with real documentation about the internals

Cheers,
- Graham

---
----
Join the Frogs!