Bug 002: Report Conformance in the Wrong Place

This is feedback on a Last Call Working Draft:

Developer Guide for Evaluation and Report Language (EARL) 1.0
W3C Working Draft 10 May 2011
http://www.w3.org/TR/2011/WD-EARL10-Guide-20110510/

The section in question here is § 4.1 Conforming EARL 1.0 Reports:

http://www.w3.org/TR/2011/WD-EARL10-Guide-20110510/#EARL10Reports

The ERT WG have specifically highlighted all of § 4 as requiring feedback.

This section is in the wrong place. It is in fact in the wrong
document: this should be part of the Evaluation and Report Language
(EARL) 1.0 Schema, i.e. EARL10-Schema in TR space.

I have no idea why the conformance section for a language should be
separate from its schema. I've been through the schema with moderate
care, and through the developer's guide with some care, and this is
the only issue whose perpetration I cannot understand. If it is not
obvious that § 4.1 is a *graph constraint section*, then I must take
pains to point that out here. This is, in short, schema information.
It belongs with the schema.

The worst part is that I read the Schema carefully before I read the
Guide. I was absolutely mystified at the lack of constraints and what
this meant for the Schema. When I got to the bottom of the Guide, I
was amused: the information I sought was there. Of course, then, this
feedback can be thought of as applying to the Schema as much as it
does to the Guide; both documents need to be changed. See Bug 001 for
more on that.

Conformance criteria for languages like this have to be treated
carefully. What you are doing is providing a route into implementing
the language. You should have conformance at the top of a
specification, not at the bottom. Conformance is the recipe for
creation, in a sense. You want to give people a sense that there is
some single concrete format that they can learn quickly, implement
precisely, and test for consistency. Conformance doesn't just help
with the third of these processes, but *all three*.

Again, then, when the conformance section is moved to the Schema
specification, put it at the top. Make a link so that people can skip
as much of the preamble as possible and go straight to the conformance
section. Treat the conformance section as being the entry point for
telling people what an EARL report is. It is like the start production
in any grammar.

-- 
Sean B. Palmer, http://inamidst.com/sbp/

Received on Tuesday, 10 May 2011 21:59:43 UTC