Re: For future 2.14 doc discussion -- increasingly realistic musical examples

[Han-Wen Nienhuys]

It's been a long day, and don't have a coherent response to such a
long mail with such good points,  but I'll just put in a little
counterpoint.

1. we actually used to have longer examples and "schubert lied in 10
steps" type of examples, in the tutorial. They were removed as they
were too intimidating and not suitable for cut & paste programming.

2. Real music examples come with real .ly examples, which are again
intimidating. The nice thing about lily is that it's perfectly well
possible to build complex things by mostly combining simple
constructs. However, that simplicity is less evident when you show the
full glorious .ly.

3. Doing a real example will be disorganized from a topic perspective:
a romantic score might have

  - x,y tuning for dynamics
  - markup hacking for complicated texts
  - page layout tweaks
  - identifier trickery to minimize duplicate typing

treating those in one section of manual text may not make things clearer.

4. The page format of a manual is actually pretty small; it doesn't
fit all that much .ly text, and you easily end up with pages of code
on end. This is already happening in the templates section, IIRC.

5. Why would we put large examples in the manual, when people can just
download them from the web, and explore them at their own leisure in a
text editor?  Maybe we should put more effort to including real
examples in the lily distribution, and amply commenting those.

2007/8/29, Trevor Bača <address@hidden>:
> 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
>
> _______________________________________________
> lilypond-devel mailing list
> address@hidden
> http://lists.gnu.org/mailman/listinfo/lilypond-devel
>
>


-- 
Han-Wen Nienhuys - address@hidden - http://www.xs4all.nl/~hanwen