Re: rewrite of SpecGL Intro

Lofton
Thanks for commenting.  My comments are in-line.

>In general, I like it.  I have quoted the whole text below and embedded 
>some comments.
>
>>The attached should replace Section 1.1 and makes Section 1.7 Roadmap to 
>>Guideline no longer needed.
>
>I'm not sure that I agree with the latter statement.  I don't see how the 
>new intro text replaces the detailed roadmap of 1.7.  I.e., if 1.7 was 
>"needed" before, it is still needed (and if it wasn't needed before, 
>...).  IMO, it was (and is) useful and ought to be kept.  Other thoughts?

I don't see what 1.7 adds, other than a list of the Guidelines, which is in 
the TOC.  The 2 paragraphs could be folded into the Section 2 bullet.



>>I modeled this after the UAAG Guideline, which I believe applied our 
>>SpecGL when it was written.  Actually, I used some of their phrasing.
>>
>>We do need to develop use scenarios, which I indicated would be in an 
>>appendix.  I think Lofton's email 2 Dec. subject: none.--clarification, 
>>provides a use case for legacy specifications.
>
>Yes, I believe that there are SpecGL use cases for legacy 
>specifications.  The referenced email is at [1].  However, the rewrite 
>below still says that they are "out of scope".  I think that should be changed.

If legacy specifications are in scope, then yes.  See below

>Full text w/ embedded comments:
>========
>
>>1. Introduction
>
>Why not have a subsection heading, "Scope", or "Scope and purpose", or 
>...?  (I'm not a fan of un-sectioned text at the subsection level.)

O.K.

>>The scope of this document is a set of requirements for W3C Technical 
>>Reports (TRs) that if satisfied, will result in TRs that are clear, 
>>implementable, and testable.
>
>This is an absolute statement, and it means:  if you satisfy these 
>requirements, then that is a *sufficient* condition that your TR will be 
>clear, implementable, and testable.  I'm not sure that I believe that.  I 
>don't want to argue issue #105 here, but compare this sentence with the 
>first sentence of 1.1 (below):  "...improve the clarity, implementability, 
>..."  So I guess I'd prefer something more along the lines of "clearer, 
>more implementable, better testable", or "will enhance the clarity, 
>implementability, and testability of TRs."

good point.

>>It decribes what goes into a TR with respect to conformance and 
>>conformance topics, dealing with how a TR establishes, defines, and 
>>presents its conformance policy. This document includes:
>>
>>     * This introductions, which provides context for understanding the 
>> requirements in section 2
>
>(Ed:  "introduction")
>
>>     * Section 2 explains fourteen guidelines. Each guideline consists of 
>> a list of requirements called "checkpoints", which must be satisfied in 
>> order to conform to this document.
>>     * Section 3 defines explains how to make claims that W3C TRs satisfy 
>> the requirements of section 2.
>
>Suggest, "conformance claims" (since that is the terminology we use in 
>many places).
>
>>It defines conformance for this document
>>     * An appendix provides use scenarios or examples of how this 
>> document could be used.
>>     * A second appendix lists all the guidelines and checkpoints into a 
>> pro-forma that is required to be completed as part of the conformance 
>> claim to this document.
>
>We should explicitly say, "This is an Implementation Conformance Statement 
>(ICS) pro-forma for this specification."  (That's what it is, and it 
>should be identified as such.)
>
>
>>A separate document, entitled "Specification Examples and Techniques 1.0" 
>>(the "ExTech document" from here on) provides suggestions and examples of 
>>how each checkpoint might be satisfied. The techniques in the ExTech 
>>document are informative examples only, and other strategies may be used 
>>or required to satisfy the checkpoints. The ExTech document is expected 
>>to be updated more frequently than the current guidelines. Developers, 
>>W3C Working Groups, users, and others are encouraged to contribute 
>>techniques and examples.
>
>
>
>>1.1. Class of Product and Audience
>>
>>This document was designed specifically to improve the readability, 
>>implementability, and testability of W3C Technical Reports.
>
>I would suggest to use "class of product (or target)" immediately.  "The 
>class of product (or target) of this specification is...".  Highlighting 
>it as a special term (same w/ "scope" above) would be nice, and a link to 
>a definition or discussion would be useful.

Its a matter of style. If I can figure out how to make it flow, then I'll 
make the change.

>>Within this Specification Guidelines document, the term "specifications' 
>>is specifically limited to W3C Technical Reports, even though these 
>>guidelines could be applied to other documents. The class of product or 
>>target W3C Technical Report is one that is in-development or being 
>>revised rather than an existing TR that pre-dates these guidelines. The 
>>checkpoints in this document are applied and conformance (to this 
>>document) achieved, as these new specfications are being written. As for 
>>legacy specifications, they may indirectly comply with the spirit or 
>>intent of some checkpoint, whichout actually satisfying all requirements 
>>in those checkpoints.
>
>This is the one bit that I disagree with -- I think we had it wrong 
>before, and it still reflects that (e.g., see [1]).  I don't think that 
>the class of product is "new TRs".  I think it is TRs.  As you mentioned 
>at the beginning, there are use cases for legacy TRs ([1] 
>again).  Therefore, aren't legacy TRs included in the "class of product"?

I guess that is correct.  We did say that the class of products was all 
TRs.  However, we do need to make a distinction between new TRs that must 
apply these guidelines and legacy TRs which don't.

>>The primary target audience of this document is specficiation authors, 
>>however, it is applicable to a broader audience including:
>>
>>     * those who review specifications during their development,
>>     * implementers of specifications,
>>     * those who use specifications to build test materials.
>>
>>It is a design goal of these guidelines the WGs can apply them in a 
>>common-sense and workable manner.
>
>-Lofton.
>
>[1] http://lists.w3.org/Archives/Public/www-qa-wg/2002Dec/0004.html

lynne

Received on Monday, 16 December 2002 14:23:52 UTC