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

[www-qa-wg] <none>

From: Lofton Henderson <lofton@rockynet.com>
Date: Sun, 24 Apr 2005 16:20:09 -0600
Message-Id: <5.1.0.14.2.20050424150251.0300bd40@rockynet.com>
To: www-qa-wg@w3.org
This set of changes will implement the "normative, optional" change, which 
WG respondents have so far agreed is a good thing to do.

This is just one set of changes that would do it, and I'm sure that other 
QAWG-ers can think of better ways to phrase or present some of the 
bits.  Or clearer explanations.  Please feel free to improve upon 
this.  Also, I have probably missed something, somewhere, that needs to be 
changed.


a.) The first change is in Introduction, first few sentences of section 1.5 
[1]:
[1] http://www.w3.org/QA/Group/2005/02/qaframe-spec/#about
[2] http://www.w3.org/QA/Group/2005/02/qaframe-spec/#conformance
==== old text ====
This document is a practical guide to writing a specification, presenting 
editors with topics to consider. Consequently, much of the document is 
non-normative recommendations labeled Good Practices. There are however, a 
limited number of normative requirements, labeled Requirements that must be 
implemented in order to conform to this document.

==== new text ====
This document is a practical guide to writing a specification, presenting 
editors with topics to consider. The normative content is contained in a 
collection of a small number of Requirements [ed: bold], and somewhat more 
Good Practices [ed: bold].  As explained in this specification's 
@@conformance clause@@ [ed:  link to [2], or a more specific subsection of 
[2]], the Requirements are necessary for claiming conformance to 
Specification Guidelines, and the Good Practices are recommendations that 
will further benefit the quality of a specification.  [ed: suggest 
paragraph break here]

b.)  Changes to 1.5.1 [3]:
[3] http://www.w3.org/QA/Group/2005/02/qaframe-spec/#structure
==== old text ====
The conformance section of this document describes the conformance 
requirements. A specification editor who wishes to write a specification 
conformant to Specification Guidelines must ensures it satisfies the 
conformance requirements in the conformance section of this document. It 
defines the Requirements as normative and the Good Practices as informative.

==== new text ====
The conformance clause of this document describes the conformance 
requirements. A specification editor who wishes to write a specification 
conformant to Specification Guidelines must ensures it satisfies the 
requirements in the conformance clause of this document.

[Ed note:  early in 1.5 [1], we talk about "conformance clause" for other 
specifications.  In 1.5.1 [3], we talked about "the @@conformance section@@ 
of this document".  Shouldn't we be consistent and use "conformance clause" 
in 1.5.1, about SpecGL?  Accordingly I changed "section" to "clause" in the 
above.]

c.) Something lost in Requirement 07 [4]?
[4] http://www.w3.org/QA/Group/2005/02/qaframe-spec/#consistent-style-principle

In the first bullet, "These keywords usually appear with an uppercase 
formatting." -- as I recall, Dom proposed and everyone agreed to some other 
wording, along the lines of "...distinctive formatting, such as upper case 
or bold."  This change apparently did not make it into the editors' draft 
yet. (Sorry, no time to look it up in the email archive right now.)

d.) Lower case keywords [2]:
[2] http://www.w3.org/QA/Group/2005/02/qaframe-spec/#conformance
Here we say, "Occurrences of these words in lowercase have normative 
implications."  In Reqt. 07, first bullet, we suggest that upper case or 
bold is the usual way to do it.  Should we follow that advice?  (I prefer 
bold to upper case, in the style of Process Document.)

e.) Changes to "Conformance Criteria" [5]:
[5] http://www.w3.org/QA/Group/2005/02/qaframe-spec/#conformance-criteria
==== old text ====
The conformance requirements of this document are denoted as 
Requirements.  All Requirements are written in imperative voice and denote 
mandatory conformance requirements.  In addition to Requirements, the 
document contains Good Practices.  Good Practices are optional and 
considered recommendations.  Their implementation or non-implementation 
does not affect conformance to this Specification Guidelines document.

To conform to this Specification Guidelines, all Requirements must be 
implemented.

==== new text ====
The conformance requirements of this document found in the Requirements and 
in the Good Practices.  The Requirements are written in the imperative 
voice and denote mandatory conformance requirements.  The are equivalent to 
the familiar MUST statements in the RFC2119 style.  In addition to 
Requirements, this document contains Good Practices.  Good Practices use 
the same imperative voice, but are optional.  They are equivalent to SHOULD 
or RECOMMENDED statements in the RFC2119 style.   Their implementation or 
non-implementation does not affect conformance to this Specification 
Guidelines document, but it is recommended to implement as many as 
possible, as the quality of the specification will benefit.

For a specification to be Specification Guidelines conformant 
[ed:  italics, and maybe link to the appropriate bullet above the 
paragraph?], all Requirements must be implemented.

[Ed note.  I was unsure if and where to put comparison to the RFC2119 
"MUST" and "SHOULD" references.  I think it is helpful, but don't feel 
strongly, and maybe it actually distracts or confuses.]

f.)  Changes to "Normative parts" [6], 1st sentence:
[6] http://www.w3.org/QA/Group/2005/02/qaframe-spec/#normative-parts
==== old text ====
The Conformance section, the Normative References section and the 
Requirements are the normative parts of this specification.

==== new text ====
The Conformance section, the Normative References section, the 
Requirements, and the Good Practices are the normative parts of this 
specification.

[Ed note.  s/normality/normativity/ in 3rd sentence.]

g.)  Changes to "Normative parts" [6], first two lines of table:
[6] http://www.w3.org/QA/Group/2005/02/qaframe-spec/#normative-parts
Change the first two lines of the table to look follows:

Requirements    Normative,
                                 mandatory
Good Practice   Normative
                                 optional

[Ed. In case the formatting is lost in this email, I'm proposing that 
"mandatory" appear under "normative" in the 1st line, and "optional" appear 
under "normative" in the 2nd line.]

h.)  Changes to "Normative parts" [6], paragraph after table:
[6] http://www.w3.org/QA/Group/2005/02/qaframe-spec/#normative-parts
I propose that the paragraph should be deleted.  It adds nothing to what 
has already been said, in prose and in the table.

i.)  Add definitions of normative and informative from [7]:
[7] http://www.w3.org/TR/2003/CR-qaframe-spec-20031110/definitions#definitions
18 months ago we had consensus definitions of normative and 
informative.  We did not resolve to change or delete them, but rather they 
simply disappeared with the big rewrite after the first CR phase.  I 
propose that we should add them back into SpecGL (and the QA Glossary).

j.)  "Specification Guidelines conformant" in "Conformance claims" [8]?
[8] http://www.w3.org/QA/Group/2005/02/qaframe-spec/#specgl-claim

In the third bullet of [5], we define the label "Specification Guidelines 
conformant".  We never use it anywhere else (and should, I think).  In 
particular, shouldn't it be somehow worked in to the section on conformance 
claims (to SpecGL)?

That's all for now.

Regards,
-Lofton.

[1] http://www.w3.org/QA/Group/2005/02/qaframe-spec/#about
[2] http://www.w3.org/QA/Group/2005/02/qaframe-spec/#conformance
[3] http://www.w3.org/QA/Group/2005/02/qaframe-spec/#structure
[4] http://www.w3.org/QA/Group/2005/02/qaframe-spec/#consistent-style-principle
[5] http://www.w3.org/QA/Group/2005/02/qaframe-spec/#conformance-criteria
[6] http://www.w3.org/QA/Group/2005/02/qaframe-spec/#normative-parts
[7] http://www.w3.org/TR/2003/CR-qaframe-spec-20031110/definitions#definitions
[8] http://www.w3.org/QA/Group/2005/02/qaframe-spec/#specgl-claim
Received on Sunday, 24 April 2005 22:20:33 GMT

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