Re: Running example

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 UTC