W3C home > Mailing lists > Public > www-qa-wg@w3.org > June 2004

"SpecLite" Response to comments

From: Lynne Rosenthal <lynne.rosenthal@nist.gov>
Date: Thu, 17 Jun 2004 23:49:31 -0400
Message-Id: <5.1.0.14.2.20040617144239.00b06ac0@mailserver.nist.gov>
To: Jeremy Carroll <jjc@hplb.hpl.hp.com>
Cc: www-qa-wg@w3.org

Hi Jeremy

Thank you for your comments.  We appreciate you taking the time to provide 
them prior to our F2F, especially given the short notice.  The comments 
were very helpful in providing us input as to both he general direction and 
specific sections of the QA Spec document.

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

Thank you.  We will be continuing the QA Spec in this style.  Our plan is 
to have complete version by early fall.

>===
>
>Detailed,
>=========
>Comments on wording of some principles.
>
>A.2 I have a weak pref for this principle to be a GP

We agree and have made this 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

The GP will be clarified to indicate that when defining the scope, it 
should not include conformance requirements (e.g., MUST statements).

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

Agree.

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

We agree and will change "address" to "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

We agree.  The principles and GPs will be simplified and rewritten as a 
short sentence.  We will do this throughout the document.

>D3 thanks for including text about OWL and RDF

We were glad to have the example.  Thanks for contributing to the earlier 
QAIG email thread on extensions.

>D3 last GP: ditto above
>D4 same comment on editorial consistency, and on the principles and first GP.

Agree.  See above.

>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)

Good suggestion.  We will link to the editor's home page which will have a 
list/link of the most current tools.

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

Good idea, we will mention WAI and I18N,  noting they are out of scope.

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

Yes, Thank you. That would be terrific.

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

Your welcome.  You have made considerable contributions to this and our 
other documents.  We appreciate the input.

>==
>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.

Agree

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

This is helpful to get an 'outside' view.  We are leaning in the same 
direction.

>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]

We haven't written about this yet, but plan to say something in the next 
version of the document.  Thank you for the reminder.

Again, thank you for the comments.  We would appreciate hearing from you, 
to acknowledge whether you accept our handling of your comments. Although 
we have accepted and agreed with your comments, please let us know if you 
are dissatisfied with our planned implementation of their resolution. We 
look forward to your reply.

regards.
Lynne
Received on Thursday, 17 June 2004 23:55:23 GMT

This archive was generated by hypermail 2.2.0 + w3c-0.30 : Thursday, 9 June 2005 12:13:16 GMT