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

Re: Running example

From: Fabian Ritzmann <Fabian.Ritzmann@Sun.COM>
Date: Thu, 13 Jul 2006 19:26:44 +0300
To: Bijan Parsia <bparsia@cs.man.ac.uk>
Cc: public-ws-policy@w3.org
Message-id: <44B67444.8060607@Sun.COM>

Bijan Parsia wrote:
> On Jul 13, 2006, at 7:24 AM, Fabian Ritzmann wrote:
>> Bijan Parsia wrote:
>>
>>> 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*!

IMHO, that's not a bad thing.

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

I guess it depends, but the document you are quoting is looking good to me.

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 16:26:54 GMT

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