Frog's Lament

classic Classic list List threaded Threaded
12 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Frog's Lament

Marc Hohl
Hello all,

I followed the (partly very emotional) discussions about
(un)documentated code
with great interest, and aside from the fact that I neither have the
technical
arguments nor the knowledge, I mostly agree with David Kastrup.

As a frog, I feel supported very well from Carl et al., but nevertheless,
I see myself still throwing little stones at random in the pond, looking at
the ripples on the surface (to stay in the picture).

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.

Ok, there are some who have absorbed the philosophy of lilypond, so they
can deliver
great patches without asking one question on the list (kudos to them!),
but I want
to improve lilypond, too, and I am not this sort of guy. And I think I
am not the only one ...
The list support is great, but in the time necessary to answer all my
questions on
a specific problem again and again, that person would have solved the
task I am working
on more quickly and perhaps even more consistently that I do. Ok, this
is not the spirit
of the whole frog thing, but I hesitate bothering developers with my
questions.

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.

It is clear that fully documentated lilypond code can't be written from
scratch,
but we have to start somewhere, and if the patch doc policy is as
restrictive as
the patch indentation policy, this will ease the work for future
developers significantly.

Then, I miss some general information of the future goals. Ok, the bugs
should be
eliminated, but rumor says that there are efforts to move functionality
from c++ to scheme.
Is this true? If yes, would it be for instance possible to write a
interface in c++
(kind of a meta-engraver) to allow engravers being coded in scheme? For
people
deeply involved in the internals, this doesn't seem to be very
important, but I think
it would improve the situation immediately.

I learned scheme for working as a frog, and now I am at a point where
even the simplest
tasks (seem to) require some additional c++ coding, so I will have to
learn c++, too.
On the other hand, my c++ code may soon be useless if someone writes
such a meta engraver
interface; therefore I hesitate to put much energy into learning a new
language.
Besides, not having to compile the sources ever and ever again makes
development much
easier, quicker and more reliable.

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.
The community cannot afford to drive away possible developers by giving
them the feeling
that there is some inner circle where information flows and where the
beginning
coder has no entry (sort of: "You don't understand the code yourself? Go
playing with
your toys then.") I don't think this is the case, although it sometimes
seems to be.

Greetings from the pond

Marc


---
----
Join the Frogs!

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Frog's Lament

Marc Hohl
Sorry, some Germanism found its way into the mail,

sed "s/documentated/documented/g"

;-)

Marc

Marc Hohl schrieb:

> Hello all,
>
> I followed the (partly very emotional) discussions about
> (un)documentated code
> with great interest, and aside from the fact that I neither have the
> technical
> arguments nor the knowledge, I mostly agree with David Kastrup.
>
> As a frog, I feel supported very well from Carl et al., but nevertheless,
> I see myself still throwing little stones at random in the pond,
> looking at
> the ripples on the surface (to stay in the picture).
>
> 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.
>
> Ok, there are some who have absorbed the philosophy of lilypond, so
> they can deliver
> great patches without asking one question on the list (kudos to
> them!), but I want
> to improve lilypond, too, and I am not this sort of guy. And I think I
> am not the only one ...
> The list support is great, but in the time necessary to answer all my
> questions on
> a specific problem again and again, that person would have solved the
> task I am working
> on more quickly and perhaps even more consistently that I do. Ok, this
> is not the spirit
> of the whole frog thing, but I hesitate bothering developers with my
> questions.
>
> 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.
>
> It is clear that fully documentated lilypond code can't be written
> from scratch,
> but we have to start somewhere, and if the patch doc policy is as
> restrictive as
> the patch indentation policy, this will ease the work for future
> developers significantly.
>
> Then, I miss some general information of the future goals. Ok, the
> bugs should be
> eliminated, but rumor says that there are efforts to move
> functionality from c++ to scheme.
> Is this true? If yes, would it be for instance possible to write a
> interface in c++
> (kind of a meta-engraver) to allow engravers being coded in scheme?
> For people
> deeply involved in the internals, this doesn't seem to be very
> important, but I think
> it would improve the situation immediately.
>
> I learned scheme for working as a frog, and now I am at a point where
> even the simplest
> tasks (seem to) require some additional c++ coding, so I will have to
> learn c++, too.
> On the other hand, my c++ code may soon be useless if someone writes
> such a meta engraver
> interface; therefore I hesitate to put much energy into learning a new
> language.
> Besides, not having to compile the sources ever and ever again makes
> development much
> easier, quicker and more reliable.
>
> 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.
> The community cannot afford to drive away possible developers by
> giving them the feeling
> that there is some inner circle where information flows and where the
> beginning
> coder has no entry (sort of: "You don't understand the code yourself?
> Go playing with
> your toys then.") I don't think this is the case, although it
> sometimes seems to be.
>
> Greetings from the pond
>
> Marc
>
>
> ---
> ----
> Join the Frogs!
>
>


---
----
Join the Frogs!

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Frog's Lament

Carl Sorensen
In reply to this post by Marc Hohl



On 11/26/09 2:56 AM, "Marc Hohl" <[hidden email]> wrote:

> Hello all,
>
> I followed the (partly very emotional) discussions about
> (un)documentated code
> with great interest, and aside from the fact that I neither have the
> technical
> arguments nor the knowledge, I mostly agree with David Kastrup.
>
> As a frog, I feel supported very well from Carl et al., but nevertheless,
> I see myself still throwing little stones at random in the pond, looking at
> the ripples on the surface (to stay in the picture).
>
> 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.
>
> Ok, there are some who have absorbed the philosophy of lilypond, so they
> can deliver
> great patches without asking one question on the list (kudos to them!),
> but I want
> to improve lilypond, too, and I am not this sort of guy. And I think I
> am not the only one ...
> The list support is great, but in the time necessary to answer all my
> questions on
> a specific problem again and again, that person would have solved the
> task I am working
> on more quickly and perhaps even more consistently that I do. Ok, this
> is not the spirit
> of the whole frog thing, but I hesitate bothering developers with my
> questions.

Two things come to mind here:

1) When any of us asks a question on the list and gets an answer, we ought
to add it to the CG.  We can either do it by writing a patch, or by writing
some text that will get added to the CG.

I volunteer to add text to the CG as part of my Frogmeister
responsibilities, but I don't have the time to follow all the questions and
answers and turn them into stuff that will be added to the CG.

2) I think that it always takes developers less time to answer questions
than to write the patch that you will produce.  It will take you longer to
write the patch than it would take some more-experienced developer, but
you're also developing some capability.

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

I think this is a great idea.  I think we have been following this policy
somewhat recently (e.g. we have asked for doc strings to be written before
the patch is accepted).  I'll try to watch out for this more in the future.

>
> It is clear that fully documentated lilypond code can't be written from
> scratch,
> but we have to start somewhere, and if the patch doc policy is as
> restrictive as
> the patch indentation policy, this will ease the work for future
> developers significantly.
>

The place where I have the most problems is in the C++ guts of LilyPond.
And there are relatively few patches that are applied in this area.  So,
while I think that asking for patches is good, I think that asking for
improved descriptions in the CG is even better.

> Then, I miss some general information of the future goals. Ok, the bugs
> should be
> eliminated, but rumor says that there are efforts to move functionality
> from c++ to scheme.
> Is this true?

As far as I know, the goal to move functionality from c++ to Scheme is not a
means to eliminate any use of c++ code.  To me, it appears that what is
hoped is that all of the management of the parsing, iterating, engraving,
and translating will remain in c++, but that all of the output creation
(both graphical and MIDI) will be in scheme.  If that is the case, then
everything can be modified in Scheme, and c++ is only needed when a new
engraver or translator is to be created.

> If yes, would it be for instance possible to write a
> interface in c++
> (kind of a meta-engraver) to allow engravers being coded in scheme? For
> people
> deeply involved in the internals, this doesn't seem to be very
> important, but I think
> it would improve the situation immediately.

I know that David has expressed a desire to have this work as well.

Personally, I think it would be very cool to have that work.  But I don't
know if it's even feasible, or how much it would reduce the performance of
LilyPond.  But if it could be done, and the performance is satisfactory, it
would certainly help future development.

>
> I learned scheme for working as a frog, and now I am at a point where
> even the simplest
> tasks (seem to) require some additional c++ coding, so I will have to
> learn c++, too.

I'm confused by this description that "the simplest tasks require c++
coding."  Can you give me an example of such simplest tasks?

> On the other hand, my c++ code may soon be useless if someone writes
> such a meta engraver
> interface; therefore I hesitate to put much energy into learning a new
> language.

I don't see a meta engraver interface coming in the near future, if ever.
If you need a new engraver, then I think the time spent to write the
engraver would be well-spent.

> Besides, not having to compile the sources ever and ever again makes
> development much
> easier, quicker and more reliable.

Yes, this is true.

>
> 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.
> The community cannot afford to drive away possible developers by giving
> them the feeling
> that there is some inner circle where information flows and where the
> beginning
> coder has no entry (sort of: "You don't understand the code yourself? Go
> playing with
> your toys then.") I don't think this is the case, although it sometimes
> seems to be.

I agree with both of your points.  There is no inner circle that wants to
hold all knowledge close.  And sometimes it seems that there is.

To me, the best way to resolve this problem is to get the knowledge out of
the gurus heads' and into the documentation.  But that is not likely to
happen by the gurus writing the documentation.  Instead, we less-experienced
developers need to document things as we learn them.

Is it fair that beginners need to document in addition to writing code?
Probably not.  But we beginners need to improve our understanding, and one
of the best ways to improve understanding is to explain it to others.  And
that will help us in our desires to contribute.

Thanks for helping clarify the issues.

Carl


---
----
Join the Frogs!

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Frog's Lament

Trevor D-2

Carl Sorensen wrote Thursday, November 26, 2009 4:31 PM

> On 11/26/09 2:56 AM, "Marc Hohl" <[hidden email]> 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.
>
> Two things come to mind here:
>
> 1) When any of us asks a question on the list and gets an answer,
> we ought
> to add it to the CG.  We can either do it by writing a patch, or
> by writing
> some text that will get added to the CG.
>
> I volunteer to add text to the CG as part of my Frogmeister
> responsibilities, but I don't have the time to follow all the
> questions and
> answers and turn them into stuff that will be added to the CG.

While I was learning how to use the Internals Reference
manual I wrote chapter 4 of the Learning Manual to make
it easier for others to follow.  It also benefitted me:
having to write down what I was learning ensured I understood
it properly (well, almost) and the developing chapter
itself became a useful reference source for me to use
as I dug deeper - it was a place to record what I had
learned.

I recommend all frogs do this with all aspects of LP
code as a section is understood.

It is possible I shall be embarking on writing an engraver
in the near future.  As this will be my first foray into
the C++ sections of LilyPond I am happy to record what I
find in the CG as I go.  Currently I'm figuring out the
anatomy of an engraver, and it's looking clearer by the
hour (yes, it takes quite a while), and I could contribute
a section on this to the CG after a few more days' study.
I'll need it written down somewhere so I can refer to it
as I begin writing anyway - so it might as well be in the
CG.

>> 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.
>
> I think this is a great idea.  I think we have been following this
> policy
> somewhat recently (e.g. we have asked for doc strings to be
> written before
> the patch is accepted).  I'll try to watch out for this more in
> the future.

More comments would be an improvement, but I think too
many will destroy the flow of the code when it is being
read by more experienced developers.  I would recommend
a brief overview at the top which sets out the purpose,
structure and method of the code.  Comments intermingled
with the code itself should only appear when the operation
is particularly obscure, but then _must_ appear and be
clearer than the code itself!

To elaborate on this point with an example, much of the
difficulty with a beginner looking at an engraver is the
nested macros which set up the underpinning structures.
While this is a difficulty, we would not want to see
identical comments in every engraver - that should be
in the CG.

Trevor



---
----
Join the Frogs!

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Frog's Lament

Graham Percival
In reply to this post by Marc Hohl
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!

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Frog's Lament

Han-Wen Nienhuys-2
In reply to this post by Carl Sorensen
On Thu, Nov 26, 2009 at 2:31 PM, Carl Sorensen <[hidden email]> wrote:

>> Then, I miss some general information of the future goals. Ok, the bugs
>> should be
>> eliminated, but rumor says that there are efforts to move functionality
>> from c++ to scheme.
>> Is this true?
>
> As far as I know, the goal to move functionality from c++ to Scheme is not a
> means to eliminate any use of c++ code.  To me, it appears that what is
> hoped is that all of the management of the parsing, iterating, engraving,
> and translating will remain in c++, but that all of the output creation
> (both graphical and MIDI) will be in scheme.  If that is the case, then
> everything can be modified in Scheme, and c++ is only needed when a new
> engraver or translator is to be created.

There is not a goal per se to move stuff from C++ to Scheme, but
rather to expose relevant (C++) interfaces to Scheme so people can
write the extensions in Scheme if they want.

Come to think of it, it's actually a neat project to write a Scheme
interface to engravers.  It would be a suitably sized project for me
to do over the christmas/newyear holidays.


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

I  have a different viewpoint.  I am mystified by the desire of some
people to mess with the most complicated parts of the program, without
having the knowledge to pull that.  It's possible to do that, but it
requires a lot of skill in absording a lot of code quickly.  From a
didactic point of view,  I don't think it is a good way to starting
learning how things work.  It's better start with small projects,
small improvements, and then gradually extend the scope of the changes
you make, to keep step with the improved understanding of the
infrastructure of the program, while you make changes.

>> The community cannot afford to drive away possible developers by giving
>> them the feeling
>> that there is some inner circle where information flows and where the
>> beginning
>> coder has no entry (sort of: "You don't understand the code yourself? Go
>> playing with
>> your toys then.") I don't think this is the case, although it sometimes
>> seems to be.
>
> I agree with both of your points.  There is no inner circle that wants to
> hold all knowledge close.  And sometimes it seems that there is.

As it is, the inner circle is very small, and I am a large part of that circle.

Here is the problem from my perspective: I don't have a lot of time to
spend on this. If you want to ask me questions, they had better be few
and very well posed, because I don't have the time or energy to deal
with a barrage of questions, especially if there is no pay-off for me
in terms usable patches to the LilyPond core.

--
Han-Wen Nienhuys - [hidden email] - http://www.xs4all.nl/~hanwen

---
----
Join the Frogs!

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Frog's Lament

Marc Hohl
In reply to this post by Carl Sorensen
Carl Sorensen schrieb:

>
> On 11/26/09 2:56 AM, "Marc Hohl" <[hidden email]> wrote:
>
>  
>> [...]
>>    
>
> Two things come to mind here:
>
> 1) When any of us asks a question on the list and gets an answer, we ought
> to add it to the CG.  We can either do it by writing a patch, or by writing
> some text that will get added to the CG.
>
> I volunteer to add text to the CG as part of my Frogmeister
> responsibilities, but I don't have the time to follow all the questions and
> answers and turn them into stuff that will be added to the CG.
>  
Perhaps we should collect the bits and pieces on a different place first
(perhaps the frog page). Collecting Information will take a lot of time,
and then, this information has to be reworked properly, and *then* it
is ready to find its way to the CG.

If you need help to get all the informations bundled together, I can offer
myself to help improving the documentation.
> [...]
>
> I'm confused by this description that "the simplest tasks require c++
> coding."  Can you give me an example of such simplest tasks?
>  
Ok, this depends on the definition of "simple". I started to work on
tablature bends,
but I am stuck, because the graphical output seems to be quite
promising, whereas
the usability and the syntax etc. isn't. There are only few comments on
my work, so
I cannot decide in which way I should move on, but it seems to me that I
have to implement
a new engraver.

Besides, I tried to work on bug #40, because I stumbled on the
limitations of the glissando
spanner while improving it for tablature. Glissandos (Glissandi?) are
often played
by electric guitar players, so I see this as part of the tablature
improvement, even if it
primarily concerns normal staves. But here I have to take into account
the accidentals
and some fingerings, and long email exchanges with Neil led to the
conclusion that
the best way to handle this is writing c code.

Perhaps the tasks looked simple and aren't, in fact. But I can't go on
doing anything
concerning functionality at the moment without c++.
> [...]
> To me, the best way to resolve this problem is to get the knowledge out of
> the gurus heads' and into the documentation.  But that is not likely to
> happen by the gurus writing the documentation.  Instead, we less-experienced
> developers need to document things as we learn them.
>  
Agreed.
> Is it fair that beginners need to document in addition to writing code?
> Probably not.  But we beginners need to improve our understanding, and one
> of the best ways to improve understanding is to explain it to others.  And
> that will help us in our desires to contribute.
>  
In my opinion, even beginners should have to write well-documented code.

I followed the thread about the indentation issues of Ian's patch
closely, and
it took a lot of changes (IIRC, Neil corrected the last parts himself
before applying
it) to get the code properly formatted. A suitable documentation will
probably not
consume such a big amount of time. One can show potential developers some
parts of well-documented code for clarification and let them rework
their patch
one or two times, and that's it (or at least, ideally).

And, moreover, it seems to be the fact that even developers closer to
the core write patches
they cannot explain some months later. This should never happen. It is a
horrendous
waste of time and energy if I have to find out what I did some months
ago, when spending
20 minutes more for describing the code in a suitable way would do the job.

Marc

---
----
Join the Frogs!

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Frog's Lament

Marc Hohl
In reply to this post by Trevor D-2
Trevor Daniels schrieb:

>
> Carl Sorensen wrote Thursday, November 26, 2009 4:31 PM
> [...]
>
> While I was learning how to use the Internals Reference
> manual I wrote chapter 4 of the Learning Manual to make
> it easier for others to follow.  It also benefitted me:
> having to write down what I was learning ensured I understood
> it properly (well, almost) and the developing chapter
> itself became a useful reference source for me to use
> as I dug deeper - it was a place to record what I had
> learned.
>
> I recommend all frogs do this with all aspects of LP
> code as a section is understood.
>
> It is possible I shall be embarking on writing an engraver
> in the near future.  As this will be my first foray into
> the C++ sections of LilyPond I am happy to record what I
> find in the CG as I go.  Currently I'm figuring out the
> anatomy of an engraver, and it's looking clearer by the
> hour (yes, it takes quite a while), and I could contribute
> a section on this to the CG after a few more days' study.
> I'll need it written down somewhere so I can refer to it
> as I begin writing anyway - so it might as well be in the
> CG.
This is very interesting for me, because it seems that I have
to work on a new engraver, too, so this information will be
*very* helpful. (I think you'll be much faster than I, but otherwise
I am willing to share my experiences, too).
> [...]
> More comments would be an improvement, but I think too
> many will destroy the flow of the code when it is being
> read by more experienced developers.  I would recommend
> a brief overview at the top which sets out the purpose,
> structure and method of the code.  Comments intermingled
> with the code itself should only appear when the operation
> is particularly obscure, but then _must_ appear and be
> clearer than the code itself!
Exactly.

We don't need comments like

;; now we add delta-x to x-dim
(set! result (+ delta-x x-dim))

but a brief description of the purpose of the function and its arguments,
perhaps followed by some clarification about the underlying algorithm
is enough. If I have to establish some helper functions, I can mark them
as such with a small comment/short description.
>
> To elaborate on this point with an example, much of the
> difficulty with a beginner looking at an engraver is the
> nested macros which set up the underpinning structures.
> While this is a difficulty, we would not want to see
> identical comments in every engraver - that should be
> in the CG.
Yes, but there should be a comment pointing at the right place in the CG
in *every* engraver.

Marc


---
----
Join the Frogs!

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Frog's Lament

Marc Hohl
In reply to this post by Han-Wen Nienhuys-2
Han-Wen Nienhuys schrieb:

> [...]
>
> There is not a goal per se to move stuff from C++ to Scheme, but
> rather to expose relevant (C++) interfaces to Scheme so people can
> write the extensions in Scheme if they want.
>
> Come to think of it, it's actually a neat project to write a Scheme
> interface to engravers.  It would be a suitably sized project for me
> to do over the christmas/newyear holidays.
>  
Sounds promising!

>
>  
>>> 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.
>>>      
>
> I  have a different viewpoint.  I am mystified by the desire of some
> people to mess with the most complicated parts of the program, without
> having the knowledge to pull that.  It's possible to do that, but it
> requires a lot of skill in absording a lot of code quickly.  From a
> didactic point of view,  I don't think it is a good way to starting
> learning how things work.  It's better start with small projects,
> small improvements, and then gradually extend the scope of the changes
> you make, to keep step with the improved understanding of the
> infrastructure of the program, while you make changes.
>  
I understand your viewpoint. At least from my personal experience,
the way into deeper levels of the program is not choosen by purpose
but by the will to improve a certain situation (I for example use tablature
very often; there are some symbols I need, and they aren't available,
so I started to improve tablature and have now come to the point where
the serious work begins - without ever wanting to dig that deep).

And how can you tell a small project from a bigger one, when you have
no experience?

>  
>>> The community cannot afford to drive away possible developers by giving
>>> them the feeling
>>> that there is some inner circle where information flows and where the
>>> beginning
>>> coder has no entry (sort of: "You don't understand the code yourself? Go
>>> playing with
>>> your toys then.") I don't think this is the case, although it sometimes
>>> seems to be.
>>>      
>> I agree with both of your points.  There is no inner circle that wants to
>> hold all knowledge close.  And sometimes it seems that there is.
>>    
>
> As it is, the inner circle is very small, and I am a large part of that circle.
>  
But I think you don't want this situation to last forever?
If you want to get more developers contributing, you'll have to
help them by commenting *new* code fragments
(I don't expect anyone scanning through the files,
trying to describe everything from scratch) and (more important)
sharing your vision about lilypond. If I get in touch with the
underlying philosophy, I can try to absorb it and write code
according to that philosophy. If I don't know where we are going,
I can't.

Marc

---
----
Join the Frogs!

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Frog's Lament

Marc Hohl
In reply to this post by Graham Percival
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!

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Frog's Lament

Ian Hulin
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

>
>


Lilypond Architecture Diagram.pdf (28K) Download Attachment
Lilypond Architecture Diagram.png (106K) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Frog's Lament

Marc Hohl
Ian Hulin schrieb:

> 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.
Hey, it looks good - great job! Thanks for sending me this.

Marc

>
> It's attached FYI.
>
> Hoffentlich ist das Ihnen behilflich.
>
> Cheers,
>
> Ian
>
>>
>>
>
>
> ------------------------------------------------------------------------
>


---
----
Join the Frogs!

Loading...