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

Re: Running example

From: Bijan Parsia <bparsia@cs.man.ac.uk>
Date: Thu, 13 Jul 2006 09:46:22 -0400
Message-Id: <250C4CE0-47BB-4297-9FE1-8876E311C819@cs.man.ac.uk>
Cc: public-ws-policy@w3.org
To: Fabian Ritzmann <Fabian.Ritzmann@Sun.COM>

On Jul 13, 2006, at 7:24 AM, Fabian Ritzmann wrote:

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

Damn...can I appeal to my years of teaching undergraduates how to  
write?!? ;)

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

But these aren't about how to write a document, but on how "all" and  
"exactly one" are commutative. I mean, the examples are schematic  
*anyway*!

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

Do you feel cross referencing between two parts of the same document  
is too inconvenient as well?

Cheers,
Bijan.
Received on Thursday, 13 July 2006 13:46:30 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Tuesday, 8 January 2008 14:20:40 GMT