- From: Lofton Henderson <lofton@rockynet.com>
- Date: Sun, 24 Apr 2005 16:20:09 -0600
- To: www-qa-wg@w3.org
- Message-Id: <5.1.0.14.2.20050424150251.0300bd40@rockynet.com>
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 UTC