W3C home > Mailing lists > Public > public-ws-policy@w3.org > July 2006

Running example

From: Bijan Parsia <bparsia@cs.man.ac.uk>
Date: Wed, 12 Jul 2006 17:48:26 -0400
Message-Id: <181C5A78-7E94-4135-AEA6-E1590B40EB7D@cs.man.ac.uk>
To: public-ws-policy@w3.org

I understand that people were vehement against not having a running  
example. I understand that "50 years of W3C spec writing" stand  
against me. My meager 10 years of reading them may be a poor counter,  
but I feel it's worth noting :)

As an implementor, I prefer the normative portions of the spec to be  
clear, clean, and compact. Interleaving examples can be *very*  
confusing and wearing. Plus, in the current document, it's somewhat  
ambiguous as to what is normative, since all the "for examples" are  
embedded in the specification. Examples are used in places where,  
imho, it's a bit silly, like for Associative, Commutative, etc.

If we are going to have examples of every bit of the spec in *this*  
spec, rather than in the primer, I would prefer that it be localized  
as was done in the RDF Revised Syntax:

The "example of every construct" occurs in section 2:

(Which is a much better intro than the actual RDF primer.)

If we *do* want examples connected to the spec, why not just have  
links to the appropriate sections of the primer?

I don't yet raise this as an issue because if "everyone" is dead set  
against it, it'd be a waste of time.

A compromise position would be to mark the examples more clearly  
(e.g., set out in a box...right now, the spec text and the examples  
tend to be separated only by a "For example, ") and provide an  
alternative version without them.

Received on Wednesday, 12 July 2006 21:48:30 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 20:38:26 UTC