Re: Request for feedback on 'lobbying' paper

[Evan Driscoll]

On 4/19/2013 4:17 PM, Urs Liska wrote:
> What I would prefer being commented on (of course I'll happily consider
> *any* comments) is something like:
> - Did I miss crucial aspects ('selling points')?
> - Will it be (given the mentioned revision) convincing for
> 'not-yet-converts'?
>   Would they understand what I'm talking about?
> - Should I try to make some aspects much shorter/give some more weight
> and room?
> - How detailed  should I include (code and score) examples, how many
> screenshots?

Personally, my main suggestion would be to try to make it much shorter.
I feel like someone would already have to pretty dedicated (or at least
very curious) to the idea to read through a 30+ page document. Yeah, I
know, it's hard to not ramble on, as evidenced by the length of this
email. :-) Doesn't mean it's good.

Alternatively, depending on how you see this document being used, I
would strongly urge you to consider making it into a set of web pages
instead of a single PDF. That way you could have a short main page that
succinctly describes the advantages as you see them (or even just lists
them), then links to more information for those who are interested.

--

I think that you should mention state closer to the front about editor
support for point and click. I think this will help alleviate one big
hangup for potential Lilypond users; I know it did for me.

<ramble>

Lilypond caught my attention when it was sort of described as a "Latex
for music", because I'm a pretty big Latex user. But in a very important
way, the two tasks are extremely different. When I write a Latex
document, Latex goes and adds text formatting and stuff, but... the
output just looks like a fancier version of the input. With Lilypond,
the source code and output bear basically no direct resemblance to each
other.

While I can't say I've really given it a fair shake with a "traditional"
editor, I was highly skeptical that I would find Lilypond alone the
right tool. I'm just using it for hobbyist purposes, so while "great
rendering!" is a nice benefit, it's not the primary attraction to
Lilypond. (For me, that would be version controlability, the ability to
store sections of music in variables for reuse later, and more
generally, programmability.) I figure that the time spent just finding
the location in the source that corresponds to mistakes in the output
would outweigh the benefits of Lilypond.

Because of that, my introduction to the tool was through Denemo, which I
viewed basically as "Latex:Lyx::Lilypond:Denemo". (Though I haven't
actually really used Lyx. :-)) But then I learned about Frescabaldi and
the point-and-click feature that Lilypond supports in general, and
suddenly actually editing the textual Lilypond source seemed like a
reasonable option. And indeed, that's what I've done since, and it works
pretty well.

</ramble>

So in your up-front list of benefits, I think you should also
specifically address this worry. Say something like "a lot of the
drawbacks you may think of about textual editing are mitigated via
editor support" and link to the section of the document where you talk
about that.

If you can think of other "worries that people might have which I can
address", you could even make that a section of the benefits.

--

One minor comment is that though I'm a big Git proponent and use it for
all of my stuff, I think you give Mercurial and maybe a couple other
systems a bit of a short shrift when you say things like "The choice for
version control today is Git". I would hedge a bit more and say "One of
the best choices for version control is Git, which is what this paper
will describe" or something like that.

Incidentally, if you want to motivate the use of version control, I
think I have a way that I suspect works reasonably well. I've taught an
undergrad compilers class twice, and my experience is that a
distressingly low proportion (about 1/2) of the students have used
version control before entering my class, so I've pimped it to both
classes and given an in-class demo. What I've found seems to get a
pretty good response is to ask the students to raise their hands if (1)
they've, when they've gotten to a point in a project where something new
works, have made a copy of their working directory saying
"my-project-4/21" or "my-project-thingy-working" so that they can go
back to it if they break something, and (2) they've been in a situation
where they *wished* they had done that but hadn't. I got lots of hands
for both of those questions, along with a couple laughs.

(I couldn't find something that presented version control the way I
wanted to show it, so I wrote a description. In the unlikely event you
want to steal portions of it, feel free; I can drop a creative commons
license on it. http://pages.cs.wisc.edu/~driscoll/software/vcs/index.html)

Also, your account on page 11 about how binary files cause Git to store
the whole file is incorrect. Well, that part is correct, but what's
incorrect is that Git *always* stores the whole files. It does not use
diff-based storage. Savings only comes when Git creates a pack file; but
that's just because pack files get compressed and the compression
algorithm will benefit from the duplicated information. But though I
haven't seen any measurements, I suspect that's often true of binary
files too.

Evan