QAF Spec WD: late LC editorial comments

Hi

as promised my delayed editorial comments.

As editorial comments, I am not expecting a formal treatment of these, 
nor am I intending to *argue* for them - some are typos etc, which I am 
sure the editors will accept; others are stylistic, and my comments are 
intended to help inform the editors and I will respect whatever 
decisions they make. I will try and put the larger comments (which tend 
to be stylistic) first, and then typos etc. I also number the comments 
(non-consecutively), which might help.


Jeremy


Document reviewed:
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/

Larger comments:

010:
Personally I would have preferred a more conventional numbering, with 
each section and subsection numbered, and the guidelines being say G1 G2 ...

020:
2.2 Requirement A: Examples
I particularly like charmod with it's [C,I,S] labels on all 
requirements. I wonder whether this would fit as an additional example.

030:
2.3 Good Practice B
URI examples ...
I liked this because this is a very real problem, but felt that I was 
having to draw on too much of my geek expertise to interpret this section.
e.g. knowing that 666.666.666.666 is not an IPv4 address, and that ~ and 
i-umlaut are not legal URI chars. Also the text below the example URIs 
and the URIs themselves could have been better connected, e.g. 
explicitly mentioning with the word "IPv6" that the second example URI 
illustrates this.
A further weakness is that RFC2396 has just been updated (RFC3986) which 
helps a bit ... and the IRI issue is in RFC3987.


040:
3.2 Requirement A. Examples
OWL might be a relevant example. The normative syntax and semantics are 
defined in OWL Semantic and Abstract Syntax in formal language; then in 
the OWL Test Cases document, the conformance statements are made with 
RFC keywords, linking back to the OWL Semantics and Abstract Syntax. 
(There are other weakness with OWL though)


050:
4.2 Optionality, examples
I particularly liked the XSL example

060:
Section 5, story.
One thing I like about the reworked QAF Spec GL is that almost all the 
stories are more concrete than in the earlier version where you avoided 
naming names. e.g. comment 050 above. I think this story, while clear, 
would be more compelling if you provided a link to the appropriate CR 
document ... and named the doc and the WG.
Also, I think that learning from your mistakes is something to be proud 
of, rather than ashamed of. It is clear that this version has been 
adequately reviewed prior to LC.

070:
5 Good Practice C: Examples
You overstate the OWL WG practice ...
Suggest last sentence.
"They even went a bit further by making a test case a necessary step in 
developing new features or modifying old features."
We never had a comprehensive suite for all features.

080:
Conformance section
I put a big stylistic suiggle down the side of my print-out, feeling 
that this section needed to be formal, looking again, I see it is only 
the words "is very simple" that gave me a sense of informality here. 
That seems more like a judgement that the reader should make, not the 
authors. Suggest s/is very simple./is as follows./


Typos etc:
200:
1.1 Good Practice B: Techniques
bullet point 1a
s/products will/products that will/

210:
Figure 2
I printed this out on a black and white printer.
The paler lines for the simple conformance were hard to make out on my 
print out. The picture could be improved by changing the colour scheme.

220:
1.2 Good Practice B: Techniques
bullet point 5
Provide hyperlink for EARL

230:
2.1 Requirement A: Examples
weakly suggest moving quote from CC/PP up to directly below bullet point 
concerning CC/PP immediately above "Could have been better"

240:
2.1 Good Practice B: Techniques
3rd main bullet s/compliment/complement/

250:
2.3
first para, third sentence "Then it is essential"
The "Then" is not grammatical. Suggest delete word leaving: "It is 
esssential" more extensive rewording could also be done, my preference 
is the single-word delete

260:
4.1 Subdivide
Last sentence of first para reads badly. 'should' is problematic.
Suggest: 'Choose subdivisions so that the benefits outweigh the drawbacks.'

280:
4.4 Requirement B
is not grammatical. Suggest
"Define how each deprecated feature ..."

290:
4.4 Good Practice C: examples
XML namespaces incorrect
suggest "deprecation of relative IRI references"

300:
5. first bullet point in section
"Benefit/Cost ... features" is not grammatical. Suggest:
"analyze the costs and benefits of each individual feature."
(note both verb changes, and change in number of object)

310:
5 Good Practice E
I found the phrasing "define which from" awkward. I suggest "define 
whether prose or formal language has priority"

320:
5 Good practice E. Techniques, 2nd bullet
"and one can't [be] modified"

330:
Conformance/Normative Parts/first para
suggest delete "as well as the labels, 'normative' and 'informative' 
within sections." It is untrue.

340:
Conformance/Normative Parts
suggest identifying the conformance section itself as normative

350:
Acknowledgements
s/Caroll/Carroll/

360:
References/OWL Test
s/J De Roo, J.J. Carroll/J.J. Carroll, J De Roo/

Received on Monday, 31 January 2005 08:37:29 UTC