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 [EMAIL PROTECTED]
_______________________________________________ lilypond-devel mailing list [email protected] http://lists.gnu.org/mailman/listinfo/lilypond-devel
