[Top][All Lists]

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

Re: other manual style issues

From: Graham Percival
Subject: Re: other manual style issues
Date: Sun, 24 Oct 2004 13:54:54 -0700

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

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.

- Graham

reply via email to

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