- From: Bijan Parsia <bparsia@cs.man.ac.uk>
- Date: Thu, 13 Jul 2006 09:46:22 -0400
- To: Fabian Ritzmann <Fabian.Ritzmann@Sun.COM>
- Cc: public-ws-policy@w3.org
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