Re: [frogs] Frog's Lament

[Ian Hulin <ian@xxxxxxxxxxxx>]

Marc Hohl wrote:
> 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?
Marc, it's work-in-progress.  I may have to re-think and  re-design it 
but  it's intended to show a new potential developer the mixture of 
languages there are in the lilypond code-base and how they interact. I 
want it to be part of a new early chapter in the CG.  An "Intended 
Audience - How You Can Help" chapter.

It's attached FYI.

Hoffentlich ist das Ihnen behilflich.

Cheers,

Ian

>

Attachment: Lilypond Architecture Diagram.pdf
Description: Adobe PDF document