Re: other manual style issues

[Graham Percival]

On 24-Oct-04, at 6:58 AM, Han-Wen Nienhuys wrote:

> these recommendations do make for a terse, formal and technical style
> of writing. It could be that we should relax these conventions a
> little, but maybe you could review the Chapter using these guidelines
> again?

I agree that the recommendations make a terse, formal, and technical
style.  I'm not certain that we should keep that, though.

IMO there's two different uses of documentation:

1)  Learning something new (ie tutorial).
2)  Being reminded of how to do something you already know about (ie 
reference manual).

A terse technical style is good for #2, but (IMO) bad for #1.

Maybe we should make a distinction in the docs: some parts are designed
for #1 (and thus use a more chatty style), while other parts are 
designed
for #2.

I definitely think that some new users would prefer a chattier style.  
Actually,
this could be a good question to ask in -user.


As an aside, I won't have much time for LilyPond stuff until this 
Friday; I have a
number of assignments and midterms this week.  I should be able to 
catch up on
that weekend, though, so it shouldn't delay the 2.4 release.

Cheers,
- Graham