[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
new docs
From: |
David Bobroff |
Subject: |
new docs |
Date: |
Mon, 02 Jun 2003 16:25:44 +0000 |
>> 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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- new docs,
David Bobroff <=