GDP: in a perfect world, nothing but RTFM

[Graham Percival]

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