RE: Running example

I'm strongly against either:
- no examples
- example for every feature/property/etc.

Relevance is the important and useful part, not completeness.  

There may be some specese that we can do to call out the examples.  In
all the xml spec that I've done, I used the <example> section to
identify examples.

Dave

> -----Original Message-----
> From: public-ws-policy-request@w3.org [mailto:public-ws-policy-
> request@w3.org] On Behalf Of Bijan Parsia
> Sent: Wednesday, July 12, 2006 4:48 PM
> To: public-ws-policy@w3.org
> Subject: Running example
> 
> 
> 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:
> 	<http://www.w3.org/TR/rdf-syntax-grammar/>
> 
> The "example of every construct" occurs in section 2:
> 	<http://www.w3.org/TR/rdf-syntax-grammar/#section-Syntax>
> 
> (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.
> 
> Cheers,
> Bijan.

Received on Wednesday, 12 July 2006 21:54:10 UTC