Re: Announcing "SpecLite"

Lofton Henderson wrote:
> [1] http://www.w3.org/TR/2004/WD-qaframe-spec-20040602/

Here is a first quick informal review of the "principles" and "good 
practice"; unfortunately I have not reviewed much of the other text. 
Please do not treat any of these comments formally.

I note that some of the text has been a bit rushed, presumably to get it 
out before your F2F, so maybe I should postpone a more detailed review 
until next publication. Please advise.


====

Summary:

I found the principles and good practices appropriate.
I would advocate that WGs working on Rec track documents that I am
involved with should follow the QA Spec Guidelines when it reaches Rec
(assuming it ends up as a more polished version of this WD).
Once again I congratulate the QAWG on the rapid work done since the tech
plenary.


===

Detailed,
=========

I started looking at the principles after having read the Introduction,
when I decided that given the short time given before your f2f it would
be best to concentrate on the normative content (the principles). I also
found that typographically and also in content that the Good Practices
were similar and fell naturally into such a top-level review.

Comments on wording of some principles.

A.2 I have a weak pref for this principle to be a GP

B.1 first GP suggest delete "Don't specify requirements"

a) it is not clear what this means
b) if it adds anything perhaps add to descriptive text under the GP

D.2 first GP suggest delete "Determine the need for each option" - the
GP is conveyed by the second sentence in the box

D.2 third GP "Address" unclear, perhaps replace with "Adequately consider"

D.3
I note an editorial inconsistency in the style of the Ps and GPs in this 
section from the earlier ones. Personally, I prefer the simple short 
imperatives in the earlier sections, with detailed comment below. I 
believe the document would benefit from consistency.

e.g. D3 Principle: first sentence only, move rest below
      D3 GP: ditto

D3 thanks for including text about OWL and RDF

D3 last GP: ditto above

D4 same comment on editorial consistency, and on the principles and 
first GP.

E - thank you for including this section -
again with the first GP suggest shortening it to maybe the second 
sentence: "Do a systematic and thorough review"
It may be helpful to include links to useful tools for ensuring quality 
of this kind, such as linking to the pubrules page or the prodspec 
mailing list page; also the XML format that many editors use could be 
mentioned here. (Concept: if you use tried-and-tested tools, and don't 
push the process boundaries too much, you get more automated support for 
this sort of quality control - e.g. the first example could indicate 
that because the WG did not have all their deliverable documents in TR 
space, some of the W3C tools for checking process quality were not 
adequately usable)
By-the-way, this section goes along way to addressing my earlier comment 
on the QAH, as to whether this is a Quality framework, or merely a test 
framework - I suspect a sentence or two (in QAH?) acknowledging further 
W3C 'quality' issues such as WAI and I18N, but noting that they are 
currently out of scope, and handing off to appropriate pages - would 
cover all the ground.

On the GP write sample code or tests, I could write up the RDF Core 
experience for you.

Acknowledgements - thanks for mentioning me. (The alphabet flatters me 
by putting me inappropriately first).


==
Conformance

I note that you haven't yet decided on how to do conformance.

Here's my 2 cents.

1) delete the ref to RFC 2119 and don't use those keywords. The curent 
short imperatives are fine; and 2119 requires that you have some sense 
of 'interoperability' that you are trying to preserve. If 2119 had been 
written by someone following your spec guidelines, then the scope 
section would, I think, been such as to not place this sort of document 
in scope.

2) I think the GPs should be normative as well as the Ps. roughly the Ps 
correspond to MUST force, and the GPs correspond to SHOULD force (I 
realise that SHOULD is unpopular with some of you; so maybe informative 
will be your call)

3) Provide an ICS which lists the Ps and GPs and allows the spec edtor 
to drop URLs in to a form.
   For the Ps the only legal values are N/A or a URL with frag ID 
identifying that part of the spec that addresses that P
   For the GPs there is a further legal value of a WG e-mail msg 
providing the rationale for not addressing that GP (or maybe a minute 
from a WG meeting deciding not to address a GP)

Then to conform means that you have correctly filled out an ICS. Every P 
has been addressed; every GP has been considered. I suppose in part it 
depends on number of Ps and GPs - any conformance process needs to be 
light enough that WGs and editors feel they get bang for buck for the 
work they put in.




Typos

Here are a few typos - just ones I saw:

"(a good place" without closing )
confomrance
"explanations or extract[s]" (i.e. missing "s")
"[@@]explain what is normative"
section D.3 longish bullet list "extension[s]" many times
tehcnologies
Car[r]oll (the hairdresser today had me down as Carol, so you did better)

Possibly:
C.1 foo-conformant ???
"non exhaustive" hyphenate?
recommendations => Recommendations


One last comment: was there text addressing the multi-document 
specification issue - i.e. one principle might be addressed in one 
document in a set, another in another. It need only be a sentence or 
two. [Apologies if it's there and I've missed it]


Have a good f2f

Jeremy

Received on Friday, 11 June 2004 14:11:33 UTC