I should clarify one point: in only the past three years, I've seen a
lot of lilypond's documentation become out of date. That makes me look
for long-term solutions for the docs. I really think of this like
software engineering: planning and designing a computer program may seem
like a waste to beginning programmers, but experienced programmers know
that it really is worth it to spend more than 50% of your time on
design, instead of programming.
* actual percentage completely made up. Don't quote some software
engineering textbook at me. :P
In a perfect world, the only discussions on -user would be this:
1) Q: how do I foo?
2) ???
3) A: RTFM section x.y.z.
4) Profit.
(Obviously step 3 would be phased nicer than RTFM.)
The missing step 2 is that we work on the docs. This isn't quite
practical -- we only upload the docs every one or two weeks, and we have
a limited amount of time/effort/interest in maintaining the docs.
But I honestly think that if everybody stopped answering questions on
-user, after a year we would have *amazing* documentation. The first
few months would suck, of course.
LSR makes this ideal much more practical. Anybody can upload an
example, and answer a question on -user with a link to that example.
The doc team can then mark certain examples to be included in our
"Snippets" section, and every so often we can move really great snippets
into the actual manual.
At the moment, there might be some useful snippets in the regtests that
aren't in LSR. As I've said before, that's considered a bug. I
honestly think that there are fewer than half a dozen such snippets --
I've looked through the regtests for good snippets, and Valentin has
done the same. If you find any, please add them to LSR.
(NB: regtests which can't be shown in LSR because they use new features
are in input/new/. This should be resolved soon)
That's why I'm so adamant that the regtests should not be on the main
doc page. Short-term pain (for a small number of advanced users, who
should know bloody well how to add stuff to LSR, anyway) for long-term
gain (having a single place to look for short examples).
Cheers,
- Graham
_______________________________________________
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user