RE: xpath-datamodel comments - grammar/punctuation/clarity/typos

As a (very!) long-time author and editor of technical (and other) 
documents, I am extremely sensitive to both side of this discussion.  I am, 
to be semi-polite about it, rather anal about grammar and punctuation, and 
I strive very hard to be clear and unambiguous about text by making both of 
those as correct as I can.  I worry about all of the rules that Mike 
mentioned (American- and British-uptightedness).  But I also recognize when 
relaxing a rule makes the text either more approachable or more useful...or 
both.

When I read Daniel's comment, I smiled rather broadly, because it was 
exactly the sort of collection that would have caught my attention, too, 
and I would certainly welcome such comments on documents for which I am 
responsible.  On the other hand, my priorities (in writing and in editing) 
are, in order:

* Be correct

* Remove and avoid ambiguity

* Eschew obfuscation (that is, be clear and minimize pedanticism)

* Be "fluid" (making the text flow better and thus often easier to recall)

Every other consideration is in the "also ran" category.  If and when I've 
satisfied the first priorities, and I happen to have time on my hands 
(awfully rare), I may go through documents for which I am responsible doing 
nothing but fixing punctuation, grammar, and awkward phrasing.

I know Mike well enough to know that he had no intent to offend, but that 
he wants the priorities to focus on accuracy, unambiguity, and clarity.  I 
don't know Daniel, but I applaud his attention to detail that includes 
things like punctuation and grammar.  Neither is wrong, of course.

Norm, of course, is a completely different animal (aren't you, Norm?).  His 
prodigious output leaves me exhausted just thinking about it, and I readily 
forgive him if his fingers miss the semicolon key and hit the comma 
instead.  He is always focused on making the documents as usable as 
possible and he is willing to overlook some niceties in the endeavor to 
make those documents correct and readable.  Whether the items that Daniel 
found fall into that ("overlook") category or not doesn't bother me at all.

Let's remember that we're all after the same goal: XQuery --- good, fast, 
*and* cheap ;^)

Take a deep breath...
   Jim

At 04:24 PM 8/19/2004 Thursday, Michael Kay wrote:

>Over the years I have learnt to make the rules I was taught at primary
>school my servant, not my master. The first test is whether the text is
>clear and unambiguous, the second test is whether it is enjoyable to read.
>Whether or not it conforms to rules taught by the old-fashioned kind of
>grammar textbook worries me little. Apart from anything else, I have
>discovered that the rules that Americans get uptight about are completely
>different from the rules that the British get uptight about, even though the
>rules are technically the same. Americans tend to worry about "which" and
>"that", the British worry about split infinitives and
>prepositions-at-the-end-of-a-sentence, but in each case we read what the
>other side writes without difficulty.
>
>I am not defending Norm's choice of punctuation, I am only defending his
>editorial freedom. (Another splice comma!) (And a sentence with no verb!)
>
>I am sure Norm will choose to apply some of the changes you suggest.
>
>Michael Kay
>
>
> > -----Original Message-----
> > From: Daniel Barclay [mailto:daniel@fgm.com]
> > Sent: 19 August 2004 22:39
> > To: Michael Kay
> > Cc: public-qt-comments@w3.org
> > Subject: Re: xpath-datamodel comments -
> > grammar/punctuation/clarity/typos
> >
> > Michael Kay wrote:
> >
> > >>>Good writers of English know when to break that rule.
> > >>
> > >>Oh, great.  I try to help clarify the specification and you start
> > >>off with an ad hominem attack.
> > >
> > >
> > > No, not at all, it was an ad hominem defence of the editor.
> >
> > Are you claiming that I was attacking the editors' abilities when all
> > I ever addressed was the state of the text, or did you mean something
> > else?
> >
> > >>So, how do you argue that the comma isn't wrong and shouldn't be a
> > >>semicolon (or other alternatives)?
> > >
> > >
> > > Lynne Truss: "Now, so many highly respected writers adopt
> > the splice comma
> > > that a rather unfair rules emerges on this one: only do it if you're
> > > famous.... E. M. Forster did it; Smoerset Maugham did it;
> > the list is
> > > endless. Done knowingly by an established writer, the comma
> > splice is
> > > effective, poetic, dashing... Done ignorantly by ignorant
> > people, it is
> > > awful."
> > >
> > > Norm Walsh is famous, give him the benefit of the doubt. [sic].
> >
> > You still seem to be dodging the issue.  I gave my analysis of why
> > the particular case should use the standard semicolon.  What's your
> > counter-analysis?
> >
> > Also, notice that your Truss quote uses semicolons as I argue and not
> > commas as you argue.
> >
> > Additionally, the specification doesn't need to be poetic or dashing,
> > and, as my analysis showed, a comma splice is _less_ effective, not
> > more.
> >
> > Why do you object to clarifying the wording of the specification?
> >
> > (On the philosophical side, given that the specification itself
> > consists of rules to follow to make sure things work right, why
> > would you object to following standard rules?
> >
> > On the practical side, why would you object to following standard
> > rules so the text is easier to understand?  Technical documentation
> > is usually complex enough to start with that it should follow
> > standard rules to try to be as clear as possible.  Additionally,
> > not being literature, its audience is different, probably including
> > a lot more people for whom English is not their native language.)
> >
> >
> > Daniel
> >
> >

========================================================================
Jim Melton --- Editor of ISO/IEC 9075-* (SQL)     Phone: +1.801.942.0144
   Editor of XQuery F&O, XQueryX, etc.              Fax : +1.801.942.3345
Oracle Corporation        Oracle Email: jim dot melton at oracle dot com
1930 Viscounti Drive      Standards email: jim dot melton at acm dot org
Sandy, UT 84093-1063 USA          Personal email: jim at melton dot name
========================================================================
=  Facts are facts.   But any opinions expressed are the opinions      =
=  only of myself and may or may not reflect the opinions of anybody   =
=  else with whom I may or may not have discussed the issues at hand.  =
========================================================================

Received on Friday, 20 August 2004 15:23:31 UTC