W3C home > Mailing lists > Public > www-qa@w3.org > January 2005

Review of QAF Spec Guidelines: summary

From: Jeremy Carroll <jjc@hplb.hpl.hp.com>
Date: Thu, 20 Jan 2005 10:10:58 +0000
Message-ID: <41EF83B2.3070903@hplb.hpl.hp.com>
To: www-qa@w3.org

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


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 

The single (not really) substantive comment is on


  "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:
"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."

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

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

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 20:40:36 UTC