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 
of spec language abuse that I have ever seen.  Definitions are supposed 
highlighted to the reader, not placed in obscurity through the addition 
[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 
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 
what they think such a style document says to a typical reader, and 
suggest a more useful signage for definitions that actually calls them 
in a normative way that doesn't cause experienced technical writers to 
into fits of perplexity.  For example, here is the style for IEEE specs:



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

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 19:55:12 UTC