Bug 011: Terms are Underdefined

This is feedback on a Last Call Working Draft:

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

All of the terms in the EARL vocabulary are very underdefined in terms
of associated prose. They should be considered more thoroughly, and
documented more fully.

An example. Consider we want to know whether we can use "FAIL" as a
earl:info text associated with a TestResult that has an earl:failed
outcome. We look up earl:info and we get the following explanation:

"additional warnings or error messages in a human-readable form"

Not very helpful. Does additional mean that it can't, for example,
repeat the information intrinsic to earl:info? In fact I picked
earl:info at random, because I knew whatever I would pick from the
specification would be under documented.

Indeed, earl:info turns out to be a disturbingly good example, because
the only specification prose defining it is tucked away in a table
cell of an appendix enumerating the properties. It doesn't even appear
as a term in its own right documented in the main body of the
specification itself.

If we look at the RDF/XML schema, we just find the same message, so no
help there.

Compare the situation with HTML 4.01. If you wanted to use the ADDRESS
element to give the page version, you'd look it up and find two very
unhelpful sentences and an ambiguous example that you'd have to guess
the answer from. In fact, it's simply not clear whether a page version
is allowed in an ADDRESS element in HTML 4.01. The two sentences don't
say so, but the example does include a CVS date variable, which is a
kind of versioning information. So who knows?

Similarly with EARL. If you put in one sentence descriptions of what
terms in a vocabulary are used for, you're just going to make people
very confused. If you intend, by short descriptions, to be very
permissive, then explicitly state that you are being permissive! If
not, don't avoid having to think up all the different scenarios that
people may want to use the properties in.

In other words, please avoid the kind of mess that HTML 4.01 made.
Document terms thoroughly. The Q element might be the best example. Be
careful not to make strange restrictions that will hamper people, as I
think those tend to create more problems than open usage; but overall
such things need to be debated and carefully investigated.

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

Received on Tuesday, 10 May 2011 23:53:06 UTC