discuss: Style Guide
Subject:
Re: Style Guide
From:
David Merrill ####@####.####
Date:
6 Jul 2001 00:23:04 -0000
Message-Id: <20010705202223.G12263@lupercalia.net>
On Thu, Jul 05, 2001 at 01:19:31PM -0400, Randy Kramer wrote:
> On a related but slightly different topic, I would have liked to see
> more examples in the section with the grammar rules -- some of them
> would benefit from an example. (Just went to look for the ones where I
> had problems -- don't notice them now except I need a definition of
> appositive.) I think if the guide goes to the trouble of listing the
> rules of grammar to be followed, it should make an effort to make them
> understandable to the anticipated audience, which is not only english
> majors.
>
> Other comments on the document:
>
> -The rules say "Do not use apostrophes to denote contractions", and I
> should probably recognize that the overriding rule is don't use
> contractions, but the rule is confusing. If you do break the rule and
> use a contraction, do you write "dont" or "don't" or what?
>
> -The section "Top 10 Topics to Watch Out For" contains a mixture of good
> and bad characteristics. Sometimes it is not clear to me which is
> which, for example, in "Topics described in sequential paragraphs rather
> than in tables", which is preferred, paragraphs or tables? (Aside: Does
> "Top 10 Topics to Watch Out For" satisfy all the rules of grammar?)
Would you please forward your comments to the authors? I'm sure they
would appreciate the feedback. And while we're at it, I'll let the
gnome-doc list know that we like their doc and would like to use it at
least in part. I'm sure they won't mind, but it's polite to ask.
And, FYI, I wrote a small section for the LAG on style issues. It is
pretty poor in comparison to this guide, but it does address a few
issues this guide doesn't. Let's make sure we fold anything from there
into this guide if we actually implement it.
--
Dr. David C. Merrill http://www.lupercalia.net
Linux Documentation Project ####@####.####
Collection Editor & Coordinator http://www.linuxdoc.org
It is practically impossible to teach good programming style to students
that have had prior exposure to BASIC: as potential programmers they are
mentally mutilated beyond hope of regeneration.
-- Edsger W. Dijkstra, SIGPLAN Notices, Volume 17, Number 5
