[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Comments on Learning Manual 3 -- Fundamental concepts
From: |
Graham Percival |
Subject: |
Re: Comments on Learning Manual 3 -- Fundamental concepts |
Date: |
Mon, 11 Aug 2008 14:37:49 -0700 |
On Sat, 9 Aug 2008 23:54:44 +0200
"Valentin Villenave" <address@hidden> wrote:
> 2008/8/9 Graham Percival <address@hidden>:
>
> > This must be a Frenchism; I winced when I saw it in some of
> > Valentin's text.itely changes. Why on earth remove the
> > parentheses? They help clarify the structure of the sentence.
>
> Actually, this is a Johnism (I don't know why he keeps asking us to
> remove parentheses).
Parentheses are discouraged in highly formal writing, but they add
clarity and the docs aren't extremely formal, so let's use them.
> > Other than specific warnings about formatting issues, don't add
> > comments to the .tely files. If you feel the need to comment
> > something about the content, it just means that the docs aren't
> > clear enough.
>
> What I have in mind when commenting an .itely file is that comments
> may be useful for the next documentation team (when the guys will
> start their own Grand Documentation Project in 10 years).
> In this specific case, theoretically doc writers are aware that the
> engraver is not used anymore...
After GDP, people shouldn't be changing the docs unless they
actually know what they're talking about. This isn't required
during GDP, of course.
Cheers,
- Graham
- Comments on Learning Manual 3 -- Fundamental concepts, John Mandereau, 2008/08/09
- Re: Comments on Learning Manual 3 -- Fundamental concepts, Trevor Daniels, 2008/08/10
- Re: Comments on Learning Manual 3 -- Fundamental concepts, John Mandereau, 2008/08/12
- Re: Comments on Learning Manual 3 -- Fundamental concepts, Trevor Daniels, 2008/08/12
- Re: Comments on Learning Manual 3 -- Fundamental concepts, Robin Bannister, 2008/08/12
- Re: Comments on Learning Manual 3 -- Fundamental concepts, Mats Bengtsson, 2008/08/12
- Re: Comments on Learning Manual 3 -- Fundamental concepts, Trevor Daniels, 2008/08/12
- Re: Comments on Learning Manual 3 -- Fundamental concepts, Robin Bannister, 2008/08/12
- Re: Comments on Learning Manual 3 -- Fundamental concepts, Trevor Daniels, 2008/08/12
- Re: Comments on Learning Manual 3 -- Fundamental concepts, Robin Bannister, 2008/08/12