- From: Lofton Henderson <lofton@rockynet.com>
- Date: Wed, 17 Dec 2003 10:51:49 -0700
- To: Lynne Rosenthal <lynne.rosenthal@nist.gov>, Dominique Hazaël-Massieux <dom@w3.org>
- Cc: www-qa-wg@w3.org
Lynne & Dom, As part of the process of my "Templates" project, I have been taking a close look at SpecGL and SpecET. Interesting perspective is provided by not having looked at them since early September! Any case, here is a collection of (I think) editorial comments, that you can file away for the next post-CR version. If you think any of these are not editorial, please feel free to kick them back and call 'em "Issues". Editorial comments on SpecGL CR text ========== (date/version: 17 Dec 2003) Ref: http://www.w3.org/TR/2003/CR-qaframe-spec-20031110/ sec 1.1: testabily -> testability (Run a spell check and you'll find other spelling errors.) sec 1.1: "provides for context" -> "provides context for" sec 1.1, 4th bullet: "of section 2" -> "of section 3" sec 1.3: "specificationand" -> "specification and" (A spell check will reveal several other cases of missing SPACE. Hmmm, maybe not, in the case that it is caused by formatting around markup?) sec 1.8, 1st bullet: "or a new edition of a specification" -- actually, somewhere else (QAF-Intro?) we say that new edition is NOT a good time to apply SpecGL. "Edition" is typically a limited re-publication, meant for errata fold-in (e.g., XML 1.0 Second Edition). Changes such as revising for SpecGL conformance are too disruptive for an "Edition". sec 2.1: " The Working Group has identified seven ways..." Which WG? Apparently we mean QAWG. And we should rephrase to eliminate that reference, e.g., "This specification identifies seven ways..." CP2.1: "If your class of product matches one or more terms in the list..." Can any given CoP match more than one term, as this implies? (I dunno' ... this is just a question that occurred to me when I read this.) CP2.3, Discussion: "one or more a categories", change "a" to "of the". CP2.4, statement: change "several" to "multiple" (or to "two or more"). [Dictionary 'several': "...an indefinite number more than two, but not very many"] CP3.1, Examples: I cannot figure out what is meant by "...only one profile can be implemented at a time." CP3.3, ConfReqs: The not-applicable exemption is missing (if profiles are not used). GL4: suggested rewording of awkward sentence -- change "Deprecated features should be avoided (e.g. for a format language, not be used by the authors and authoring tools) and may be removed in some future version, at which time the feature becomes obsolete." to "Deprecated features should be avoided, e.g. for a format language, not be used by the authors and authoring tools. A deprecated feature may be removed in some future version, at which time it becomes obsolete." GL4, 2nd pgph, 2nd sentence pretty much duplicates the above. All CP: Editors should read each Rationale. In a number of CPs, some additional sentence(s) of "Rationale" should really be "Discussion" or "Examples". GL5: "implementation dependent values (or features)" -- definition is garbled. CP5.1, statement: "State the circumstances for when discretionary items are allowed." This does not relate very well to the ConfReqs, which say "The specification MUST indicate the rationale for the discretionary items and MUST identify by labeling all discretionary items." A better CP statement would be something like, "Identify and justify any discretionary items." [Note. Other possibility is that statement is accurate and ConfReqs are wrong.] CP5.3, statement & ConfReqs: There are 3 occurrences of "items". Isn't this CP specifically about "discretionary choices", which is one of the three types of "discretionary items"? If "yes", then the 3 occurrences of "items" are incorrect -- change to "choices". (If "no", then this becomes a substantive issue, not editorial -- this CP used to be about discretionary choices and seems to have mutated). GL6, 2nd pgph: "extensions are be allowed" -> "extensions are allowed" GL6, 3rd pgph, the last sentence -- "Dimensions of variability (e.g., modules, profiles, levels) are not extensions if the specification defines them or allows them to be defined" -- is very mysterious and out of place! I only know what it means because I remember the issue discussions. Suggestion: move it to the very end of the GL verbiage, after "Extensions are a DoV", and clarify wording along the lines of: "Note. Any Dimensions of Variability that the specification itself uses or allows -- e.g., modules, profiles, levels -- are not considered to be extensions." [P.S.... It gives me a headache to think about the meta-DoV question, of whether this (and the original) wording should exempt the Extensions DoV.] CP6.1, ConfReqs: I find the language potentially confusing in 2nd bullet ("[spec must define] the scope of the extensions") and 3rd bullet ("[...] any limitations or restrictions on the use of the extension"). "*the* extensions" and "*the* extension" implies that the spec is actually defining extensions, as opposed to rules and constraints on allowable extensions. Suggestions: "the scope of allowable extensions" and "any limitations or restrictions on implementation use of extensions". CP6.1, Rationale: "If extensions are not allowed, then it should be clear to the reader that not only are extensions not allowed, but the circumstances under which they are not allowed". This is confusing to me. As I read the beginning of the sentence, "not allowed", I'm thinking unconditional, and then the sentence ends with "under which circumstances" (conditional). This sentence would not be missed, as it is rephrasing in a (IMO) confusing way what is said (IMO) clearly in ConfReqs. CP6.3, Statement: suggested rewording, "Define a uniform mechanism for allowable extensions." CP6.5, Rationale: "negative affect" -> "negative effect" CP7.1, Rationale: "...as well as those statements that are desirable or allowed". Is it the "statements" that are desirable (SHOULD) or allowed (MAY)? (Aren't SHOULD and MAY statements also potentially testable, but their difference from MUST is whether or not the result of the test affects conformance determination?). CP7.2, Definition: "Normative content is *the* prescriptive part..". It's unclear to me whether we intend to define "a bit of normative content", or "the totality of normative content" here. If the latter, okay. If the former, it might be better to say something like "Normative content is *a* prescriptive part.." or "...comprises prescriptive parts". CP7.2: The box separator line between Rationale and Discussion is missing. CP7.4, ConfReqs: is "all" contradicted by the following "minimally"? CP 7.4, Rationale: The first sentence is a thinly disguised restatement of ConfReq. Perhaps better would be something like, "Easy discovery of critical conformance information enables quick and clear understanding of the conformance policy." GL9, 1st sentence: I don't understand the sentence. If there were a full stop (PERIOD) after "...types of conformance," ... then that part makes sense. But the bits after "in order to" lose me and confuse me (about the whole sentence). GL9, 1st paragraph: In fact, I don't see how the whole 1st paragraph relates to the 5 ckpts of GL9, except for its last sentence. Suggestion: rewrite it to summarize/overview the content of the GL9 ckpts, or delete it. CP9.1, ConfReqs: suggest changing "...information about the subject which is claiming conformance" to "...information about the subject for which conformance is being claimed." (or maybe "...object of the conformance claim"?) CP9.2, Discussion: it doesn't relate very well to the subject of the CP or to the ConfReqs. If there *is* a connection, there should be a little more verbiage to expose the connection. CP9.3, Discussion: what does "relevant assuring parties" mean? CP9.4, Rationale: Suggestion: reverse the order of the two sentences. Also, I'm confused by the first half of the (current) 2nd sentence -- I don't understand what it's trying to say with "minimal list of items supported...". For example, our SpecGL ICS is a maximal list -- by listing every checkpoint, it (implicitly) subsumes every conformance requirement of SpecGL. On the other hand, I do understand the definition of ICS in the glossary, and would suggest that some of its wording (or the wording of pgphs 2/3/4 of the GL9 verbiage) be adapted here. CP9.4, Rationale: Finally ... is it a Rationale or Discussion? I would think a Rationale would be more like, "Having an ICS proforma in the specification provides and encourages use of a common detailed conformance data template, which facilitates evaluation and comparison of conformance claims." CP10.2: There is no formatting separation between ConfReqs and Rationale. all CPs: each CP in CR version of SpecGL points to a SpecET section that is paired with (points back to) the preceding *WD* SpecGL version. Sec 4.5: notice the nasty formatting glitch of the blockquote in the Conformance Claim example (unless your browser window happens to be just the right width).
Received on Wednesday, 17 December 2003 12:53:09 UTC