Re: Request for feedback on 'lobbying' paper

[Janek Warchoł]

Hi,

excellent!!

2013/4/20 Urs Liska <address@hidden>:
> Of course it isn't fair to keep a judgment in one's heart that is based
> on software more than a decade old, but my most prominent recollection
> of my work with Finale is:
> - Enter some music
> - Make corrections:
>   - Move an object
>   - switch directions (of stems, slurs ...)
>   - break beams manually
> - Hit "Update Layout"
> - Tear my hair out because Finale reverted (as an average)
>   half of my manual decisions.
>   Then I didn't have the faintest idea that there is something
>   like a 'text format' where such decisions could be
>   stored explicitely

That's exactly what made me hate Finale several years ago.  I had a
dozen-page-long piece for choir with piano accompaniment (it was
pretty simple), i've entered the music, moved all notes around to
please my eye.  So far so good.  A month later i've spotted a missing
accidental in piano part, added it, and (even without hitting any
"update layout" if i remember correctly) everything was ruined.  From
that day Finale and I are deadly enemies.
I think it was with Finale 2005.  However, things might've changed.

As for the text, here are my remarks so far (btw, is this already in a
git repo?  If so, maybe i'd write a pull request):

I'd definitely make it shorter, so that interested people will read it
in whole instead of just skimming through it ("because it's too long
to read") and ending up being freaked out by the code examples.  I'd
aim for 12 pages, with 20 being absolute maximum.

"traditionally these [WYSIWYG] programs have binary file formats that
usually are more memory efficient"
huh?? Maybe i'm missign something, but binary/XML files are bigger and
don't compress. See
http://www.terminally-incoherent.com/blog/2012/05/21/why-plain-text/
(this may give you some addtional arguments for plain text, and it's
an interesting blog anyway)

I suggest to give an example under "maintainable": a fragment of an
XML/binary file and some simple LaTeX.  This will *shock* readers :D
They'll despise Word immediately, mwahahaha!

Also, make a note explaining what's the difference between how the
file is displayed and what's actually inside it.  I.e. i'm sure that
most people think that when they open a Word document, the things they
see are what's inside the file.  They don't realize what the file
really looks like (i.e. that it's binary).

I sggst to Make the Markdown example simpler.  Just a copy of html example.

"As a first approximation you may understand version control as a huge
and infinitely flexible undo/redo implementation."
This is a *very* good description (maybe just replace "huge and
infinitely flexible" with "infinitely flexible and powerful" - to me
"huge" has some negative connotations).  And add just a note that it
gives you access to *years* of history - i'm sure people don't realize
that with VCS they could see what they were doing in the previous
century, when they used a different computer, different os, and were
living on another continent.

I wouldn't go down into details and use new "techy" words like
"repository" and "working tree" in the "gentle introduction to VCS".
Abstract away as much as you can, and leave only the user-related
bits.

Make the git code example simpler.

In "gentle introduction", use "save" and "load" instead of "commit"
and "checkout".

"This may not seem necessary in this example, but you’ll appreciate it
when the diff shows you exactly the seven changed lines in a file with
more than 2.000 lines."
Speak of pages, not lines, so that ordinary people will understand better.

Drop the part about git having problems with binary file storage.
Drop the listing of commits, people will freak out when they see SHAs.
 Move the part about checkouts to advanced part, or at least make it
simpler.

The part about "syntax highlightning" will probably freak people out.
Rather, use just sth like "Dedicated editors integrate the whole
development process in one program, offering tools to insert commands,
provide a document outline, handle errors, preview etc. Depending on
the level of assistance one may also call these programs Integrated
Development Environment, or short IDE"

I'd simplify text about floats a lot.

Mention Helmholtz pitch notation in the LilyPond syntax intro.

Instead of using "crotchet", say "quarter note" as the connection with
duration 4 is more explicit.  Also, for even better understanding,
start with 8ths or 16ths.

Drop using \relative, that only introduces unnecessary complexity.
Instead, show how one can reuse a variable by transposising it (
\music \music \transpose c c' \music ).

I suggest to recommend only Frescobaldi.  As you wrote, Emacs and vim
don't fit the target audience, Denemo is not strictly about plain
text; LilyPondTool is nice but since it's development halted,
Frescobaldi seems a better choice anyway.  Other editors are, imo, not
worth recommending compared to Frescobaldi (i don't mean they're bad,
but they only make sense to people who already use them for other
tasks, and that's a case similar to Emacs/vim).

Don't write "code completion" - write "it will show you possible
commands when you start typing" or sth. like that.

Don't use specific terms like "point-and-click" - just describe what it does.

I'll write more tomorrow.
best,
Janek