[frogs] Re: LSR snippets for contributors and Frogs

[Graham Percival <graham@xxxxxxxxxxxxxxxxx>]

On Fri, Jul 24, 2009 at 08:40:31PM +0200, Valentin Villenave wrote:
> 2009/7/24 Graham Percival <graham@xxxxxxxxxxxxxxxxx>:
> > Really?  "Advanced scheme" comes to _my_ mind first -- 3 or 4
> > years ago, when I made the very first list of categories (in the
> > pre-tag days).  Now, I'm not certain if that tag still exists, but
> > whatever tag corresponds to NR 6 should be used for these scheme
> > things.
> 
> No. The tag is named "Scheme language", and is meant -- as is NR 6 --
> to demonstrates how the Scheme interface to Lily works, not to
> demonstrate how to get intimate with the way Lily processes grobs etc.
> More precisely, NR6 is about Scheme stuff that can help you engraving
> your scores. You certainly won't find stuff like Mark's snippet
> anywhere in NR6 (nor anywhere else, as Mark pointed out).

Ok.

> > This is a crappy idea.
> 
> Thanks for allowing me to paste the reply I had prepared in advance :)

Dude, you *asked* me to say that.  I figured that fulfilling your
request was only polite!

(comic posted at the music camp I was just at:
person 1: Am I a bad pianist?
person 2: Yes, you are.
1: You know, when somebody asks something like that, you're
supposed to say something reassuring!  :(
2: Ok.  Rest assured, you're a bad pianist.
)

> Graham, I'd like to friendly invite you to go through your mailbox
> archive and search for what you answered me when, on April 17, 2007, I
> suggested that we should have tagging ability in the LSR.

I don't keep mailbox archives.  I treat email like conversations:
we don't record all our casual conversations with friends, so why
record all email conversations?  If there's a TODO associated with
an email, I'll keep it... but only until I process that item.

> On August 15, 2008, I told you: "we should think about making a second
> Manual, for advanced users and developers (which might allow us to
> make the actual User Manual lighter, by the way). It would be a
> companion for the internal Reference, helping people to browse source
> files and to understand how things work, etc." What did you have to
> say? "This is a crappy idea".
> Yet, several months later, hey, guess what? It was *you* who initiated
> the CG, which was roughly what I had in mind.

Yes, but the CG that I'm working on doesn't include tons of info
about internals.  I'm documenting the processes and policies --
how to get git sorted out, what doc policies to adhere to
(including double-spaced sentences), and checklists for releases.

More to the point, *I'm* willing and able to work on most of the
above.  For anything that I couldn't do on my own (such as a
definitive set of git instructions), I'm willing to scream and
kick my feet until it happens.


I do *not* feel the same about the internals.  And last Aug, who
was around who could write such material?  Or rather, who was
around with the knowledge, time, and interest?  I'm all for
"bottom-up" development.  If contributors want to work on IR+
stuff for the CG, great!

Now, from time to time I think it's necessary to have "top-down"
development.  I'll say "here's the goal, and now I'm going to
guilt-trip anybody possible into working on it".  That's what I
did in GDP, that's what I did to Carl to set up the Frogs, etc.
But these should be kept to an absolute minimum.


> And I won't even mention how pissed you were on March 10, 2008, when I
> launched the first beta LilyReport...

Yes.  That was 3 months into your rewrite of NR 6, a task that
should have taken 10-15 hours.

> So, Graham, please let me, once again, wholeheartedly thank you for
> enlightening my path to Wisdom and Relevance :-)

Are you suggesting that I make mistakes?  Yes, I do.  I'm still
uncertain about whether reinstating LSR was a good idea or not.  I
agree that adding tags to LSR was worth it (given that we had
already spent all the effort to get LSR integrated into our doc
build process).

I also admit that the Report turned out to be a great idea.
Perhaps I shouldn't have worried so much about GDP -- although I'd
argue that it was my main task to worrk about GDP, and you should
have (and probably did) factor that into disregarding my dislike
of this idea -- but it definitely delayed the NR 6 work.


In general, our disagreements are due to an estimation of the
relative importance of development tasks.  I'm generally a
conservative person, so I think that fixing bugs and delivering a
stable, consistent program is very important.  Any time that I
hear a new idea, I think about how much effort that will take away
from stabilization (fixing bugs, fixing documentation, etc).  Not
just my own time, but other people's time.

For example, LM 5.3 begins with
----
TODO: this is really old stuff from the really old tutorial.
Rewrite, fix, etc. Or maybe delete entirely. -gp
Include section on tags -td
and then move to section 5. Working ... -td 
----
The entire (brief) section is almost certainly included earlier in
the LM -- possibly even in the tutorial.  If not, it certainly
/should/ be covered in LM 3.

**This** is the kind of thing I mean when I say "stabilization".
There are dozens of such glaring problems in the docs.  Each one
only takes an hour or two to fix, but whenever something new comes
up, they get pushed lower on the priority scale.

Some new features _are_ worth delaying that work.  Getting the CG
to a point where new contributors don't need to spend 12 hours
reading git tutorials before they can get started _is_ worth it.
IMO, at least.  Other new features _are not_ worth such delays.

Cheers,
- Graham

---

----
Join the Frogs!