[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

GDP: in a perfect world, nothing but RTFM

From: Graham Percival
Subject: GDP: in a perfect world, nothing but RTFM
Date: Tue, 11 Sep 2007 13:33:07 -0700
User-agent: Icedove (X11/20070607)

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).

- Graham

reply via email to

[Prev in Thread] Current Thread [Next in Thread]