[Top][All Lists]

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

other manual style issues

From: Han-Wen Nienhuys
Subject: other manual style issues
Date: Sun, 24 Oct 2004 15:58:28 +0200

address@hidden writes:
> Ok, now that the silly gender issues have their own thread, let's 
> discuss real issues.

I have some more style issues.  The lilypond.tely files lists some
guidelines for writing the docuemntation. I noticed that the new
chapter on templates does not follow these recommendations,
in particular

        * Do not refer to LilyPond in the text.  The reader knows what the
        manual is about.

        * Do not explicitly refer to the reader/user.  There is no one else
        besides the reader and the writer.

In general, I think that the text should only refer to the reader
personally, when the writer takes a personal viewpoint as well,
i.e. when writing "I, we, me"

        * Do not use abbreviations (don't, won't, etc.).

        * Avoid fluff (``Notice that,'' ``as you can see,'' ``Currently,'') 

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


 Han-Wen Nienhuys   |   address@hidden   | 

reply via email to

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