For future 2.14 doc discussion -- increasingly realistic musical examples

[Trevor Bača]

Hi,

It looks like we're getting close to a 2.12 release, which is awesome.
It's been quite amazing to watch the increase of new features and, in
some cases, entire new subsystems enter the program over the last
couple of major releases.

First a background observation and then a specific suggestion for the
coming documentation work on the 2.13 / 2.14 cycle of releases.

The background observation (warning: highly opinionated subject matter
coming!) is that some of the most impressive features that we've added
to lily over the last couple of releases have been the hardest to
demonstrate to outsiders or newcomers. The vertical (skyline)
improvements and the auto table-of-contents making stuff are good
examples -- both are incredibly powerful features and both are quite
hard to wow outsiders with. I take this as an excellent sign because
it means that we're still doing the deeply structural work that
separates excellent programming models (like TeX and LaTeX) from kinda
crappy models that have been dressed up with a lot of surface features
(like MS Word and Powerpoint). Not, btw, that lily in any way lacks
"surface features" -- our collection of individual glyphs, for
example, is both enormous and ever-growing. On the other hand, one of
the things that (again, in my competely subjective opinion) now seems
to wow outsiders the most is the extent and organization of our
manual. The docs at this point are probably one of the best organized
of any opensource project and I think we probably convert more
*potential users* into *actual users* because of the docs than for any
other reason; we owe Graham (and also the language translation teams)
a huge debt of gratitude in this regard.

Again, these are obviously my very subjective opinions and certainly
it would be good for others to chime in here. But if I'm right that
the docs are probably now doing an increasingly good job of attracting
new users, then I think it makes sense to offer the following
suggestion for the 2.13 / 2.14 cycle of releases: I think we might
really benefit by starting to work in increasingly musically
"realistic" examples into the docs. One thing that both Finale and
Sibelius (and SCORE before them) have been very good at doing is
littering their respective manuals with examples that look like (more
of lesss) convincing notation on almost every page. It's my opinion
that we're a little behind in this respect: turning to chapter 8 on
text in our own manual, for example, we have extensive instructions on
the use and construction of markup, but mostly unconvincing examples
of the actual directives themselves, whereas this sort of thing is
unusual in the manuals of the commercial notation programs. (We could,
for example, probably replace instances of "longtext" and
"longlongtext" in the very first section with any number of long but
beautiful bits of German score directives from probably any bit of
Mahler, for example.)

PLEASE understand that I'm not criticizing the development of our docs
(or the core package); our process is correct: *first* just get docs
out there (instead of leaving the feature naked of any documentation)
and *later* go back and tweak and refine. It's just that I think that
maybe we're ready for some of the "tweaking and refining" part of the
process, maybe starting a little bit in the  2.13 / 2.14 cycle of
releases.

At least four things make this suggestion difficult:

1. It's *much* easier said than done. If we're looking for a snippet
that shows the positioning of the relative widths of text, what's the
right way to find something that's musically "realistic" in such a
stripped-down context?

2. "Realistic" examples are more complicated that "minimal" examples,
which has been our focus for some time now (because we like users to
be able to look at minimal examples and understand what's going on in
the input). Ideally, we can hunt for examples that are both realistic
and as close to minimal as possible ... but this is, of course,
difficult.

3. If our manual snippets start to look like actual music, well then,
*what type* of actual music? Classical, Romantic? 20th, 21st century?
Or do we make an effort to make the examples free of overly strong
references to any particular type of scoremaking? Or do we care about
such a type of consistency (my preferred answer is not to worry about
it too much)?

4. Maybe the easiest way to get more musically realistic examples to
borrow from bits of actual scores. If we borrow from Classical and
Romantic scores, we're probably (maybe?) safe from copyright problems.
But it can be hard to tell and we don't want to accidentally step on a
copyright landmine.


But there are a couple of mitigating factors that might make this work
somewhat easier, too:

1. The work is definitely incremental and has almost no dependencies.
We can, for example, groom the examples in just chapter 8, say,
without having to worry about any of the examples in other parts of
the docs. And there's no pressure to change too much at one time since
the examples we have are already completely valid.

2. We can probably solicit interested users on -user to help with the
process since the requirement for contributing a more musically
realistic example is essentially musical knowledge and interest
(rather than anything about program structure or internals). So maybe
the work doesn't fall back to the doc developers but to interested
users instead.


* * *

Anyway, there it is. Both the number of new features and the maturity
of docs is increasing tremendously. I think we may be getting close to
the time when we can profitably refine the musical contents of
examples throughout the docs and win ourselves even more new users in
the process.

Food for thought.

:-)




-- 
Trevor Bača
address@hidden