new docs

[David Bobroff]

>> I find it much easier
>> to see an example of something like what I'm trying to do and see how
>> it is done and then make use of the method.
>
>I learn the same way.  There are many examples in the input/ directory
>(in the web docs, look at the "tips n' tricks" and "regression test"
>links), or else read Mutopia.

I think this is actually the way humans generally learn.  We build up a
personal library of separate experiences and then form generalizations from
them.  There are many useful examples available but the problem is finding
a short path to them.

>In the index,
>http://lilypond.org/development/Documentation/user/out-www/lilypond/Index.h
tml
>it's true that we have "MultimeasureRest" without a pointer to that spot
>under "Rests", although the page on Rests has a link to Multimeasure
>rests... would the index be much better if we had a "rest, multimeasure"
entry
>as well?

I think in general the index should lead the user from a specific question
about <whatever> to a short, clear, simple, description of how to do X.
For example, Text Markup is something that will frequently need adjustment.
 I happen to know that this involves "padding" because I've asked about
this on the list and been told to look at the padding information.  A well
organized index would have a sub-heading under "Text markup" called
"adjusting" or something.  This sub-heading should then lead me to
"padding" and how to use it.  "Padding," while it is useful nomenclature
within Lilypond syntax is not intuitive for a new user.  This principle can
be applied to any aspect of the index.

>You mentioned that you're a novice user... want to help write the docs? 
>When I was a novice (I'm being optimistic in using the past tense here!
>:), I thought that novices were the best people to be writing docs,
>since everything isn't obvious to us.  I still think that novices are
>good for writing docs, BTW.  Want to help?

I agree that novices are likely the best to write docs.  If you want to ask
directions in a strange city, ask someone who moved there a year ago, not a
native.  As for helping; I'm a bit hestitant to offer to dive in and help
for the simple reason that I'm not sure I could devote enough attention to
it.  On the other hand, I've been mostly a taker and not much of a giver to
this project and I certainly would like to contribute to it.

>If you're interested, feel free to ask me any
>questions about how the docs are organized, how to write texinfo, how to
>make a patch, etc.  I often "adopt" Linux newbies, so don't be scared to
>ask me any question, no matter how silly is seems.

Well, it also seems like a way for me to become more knowlegable about
Linux which would be an additional plus for me.  Should this discussion be
moved off-list?

-David