Re: [frogs] Frog's Lament

[Marc Hohl <marc@xxxxxxxxxx>]

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?
>  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
>   
Sounds promising! I am looking forward to it am am
willing to contribute to it.


Marc


---
----
Join the Frogs!