Review of QAF Spec Guidelines: summary

This is a summary of my (forthcoming) review of:

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

Congratulations to the QA WG in bringing this document to Last Call.
Overall I am very happy with it, and believe it should progress along 
the Rec track. I think editors and WGs would benefit by choosing to 
conform to this specification.

I have only one even slightly substantive comment (below), and a number 
of editorial comments (mainly, but not exclusively, typos). I will 
probably not send my editorial comments until late next week.

A few things I particularly liked:

- the tone: this document reads to me as coming alongside an editor in 
their task, and trying to help them.

- the conformance section (substantively, not editorially): the 
substance of conformance consisted of things that almost all editors 
would agree are important, but can, and often do, get lost in the 
cracks. By setting a low base-line of mandatory requirements, this 
specification may well help raise the quality of W3C recommendations, by 
being an achievable, but non-trivial, goal for almost all WGs.

- the negative examples: I feel that these are much improved by being 
made concrete and related to technologies that many of the target 
audience will have some familiarity with, e.g. the XSLT exception 
example. I felt that this examples were presented in a thoughtful but 
non-judgemental way which read, at least to me, as helpful rather than 
self-righteous.

The single (not really) substantive comment is on

http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#deprecated-feature-principle

  "Identify deprecated features."

is slightly too strong, since the informative text below starts " When a 
technology evolves,".

What to do with a first version of a technology is usually "N/A", and 
admittedly the simple step of "This is a first version, so we have no 
deprecated featues, and don't need to document it at all" does fulfil 
this requirement.

Although, for example OWL, in its first version, does provide:
http://www.w3.org/TR/2004/REC-owl-ref-20040210/#appD
"Changes from DAML+OIL"
which does identify features deprecated from the member submission 
DAML+OIL from which OWL evolved.

I think this comment could be addressed by a sentence early in the 
section, maybe the very first sentence, like "Not normally applicable to 
first versions of a specification."

e.g.
[[
4.4 Deprecation

The need for deprecation comes ...
]]

==>

[[
4.4 Deprecation
        *This section is normally not applicable to
         first versions of a specification*
The need for deprecation comes ...
]]

Of course, the danger is in that in any weakening of the language one 
could end up having inappropriate N/As, but I suspect most editors and 
WG know if they really truely are working on a first version or not.

Good luck

Jeremy

Received on Thursday, 20 January 2005 10:14:46 UTC