Re: Running example

Bijan Parsia wrote:

> 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 :)

I guess I can put almost 10 years of implementing specs against that. :-)

> 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.

Personally, I'd prefer to have a concise example even for the trivial 
cases. I find it easier to understand when I have formatted XML right in 
front of me or maybe it's because English is not my mother tongue.

> 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 feel strongly where exactly the examples should be placed and 
how they should be formatted, but I'd rather keep them in the spec 
itself. Constant cross-referencing between two documents is too 
inconvenient.

Fabian


-- 
Fabian Ritzmann
Sun Microsystems, Inc.
Stella Business Park             Phone +358-9-525 562 96
Lars Sonckin kaari 12            Fax   +358-9-525 562 52
02600 Espoo                      Email Fabian.Ritzmann@Sun.COM
Finland

Received on Thursday, 13 July 2006 13:20:06 UTC