Re: problems with learning lilypond

[Graham Percival]

On Thu, Aug 13, 2009 at 04:54:15PM -0700, David Fedoruk wrote:
> Also, remember that my time zone is GMT -8, so I am one of the last
> people on this list to see anything posted.

Same here, being in Burnaby.

> If I had to say one thing that is wrong with documentation is that the
> people doing the documentation assume to much about the state of the
> reader's knowledge. What may seem obvious to you, may not be to the
> person reading your documentation.

I disagree here.  We spent a lot of time thinking, talking, and
planning out those assumptions.

At the beginning of the Learning Manual, we assume that the reader
knows nothing other than having a slight familiarity with their
operating system.  (i.e. windows users should know what a
"double-click" is)

In the middle of the LM, we assume that the reader has read (and
understood) the earlier parts** of the LM -- or at least, that the
reader would be willing to go back and review previous material.
I agree this assumption is slightly tenuous, but if we couldn't
make this assumption, the docs could easily be three times as
long.
** if you find any instance where this is not true, please let us
know!  The LM is designed to be read sequentially, explaining each
term and concept as they come... we consider any deviation from
this to be a serious problem.

In the Notation Reference, we assume that the user has read (and
understood) the LM.  Again, maybe this is a flawed assumption, but
again, we could triple the doc lenth (not to mention the doc
writers' workload!) otherwise.

In the Internals Reference, we assume that people know a lot.
Partly because this is advanced stuff, but mostly because we don't
have enough doc writer effort to smooth this over.

Cheers,
- Graham