SpecGL editorial comments

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