W3C home > Mailing lists > Public > spec-prod@w3.org > October to December 2004

Square-bracket output of Definition in specs is bogus

From: Roy T. Fielding <fielding@gbiv.com>
Date: Mon, 6 Dec 2004 13:24:32 -0800
Message-Id: <388A9112-47CD-11D9-A270-000D93324AD6@gbiv.com>
To: spec-prod@w3.org

The output chosen for definitions in W3C specs is easily the worst 
example
of spec language abuse that I have ever seen.  Definitions are supposed 
to
highlighted to the reader, not placed in obscurity through the addition 
of
[Definition: ...].  Mark-up should never obscure CONTENT.

Under normal English, anything inside square brackets can be removed.
In technical specifications, anything inside parentheses or square 
brackets
is non-normative or indicative of an editorial addition in order to
clarify a quote taken from some other source.  Obviously, neither is
the case for definitions.

I suggest that the W3C ask a literature department (like Harvard or 
Chicago)
what they think such a style document says to a typical reader, and 
perhaps
suggest a more useful signage for definitions that actually calls them 
out
in a normative way that doesn't cause experienced technical writers to 
go
into fits of perplexity.  For example, here is the style for IEEE specs:

   http://standards.ieee.org/guides/style/section4.html#527


Cheers,

Roy T. Fielding                            <http://roy.gbiv.com/>
Chief Scientist, Day Software              <http://www.day.com/>
Received on Monday, 6 December 2004 21:24:36 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Saturday, 10 March 2012 06:19:13 GMT