Re: rewrite of SpecGL Intro

At 12:33 PM 12/5/02 -0500, Lynne Rosenthal wrote:
>Attached is my rewrite of the SpecGL Introduction to make sure our Scope 
>and Class of Product are clearly communicated.

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 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.

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.)

>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."

>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.

>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"?


>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

Received on Sunday, 15 December 2002 13:08:41 UTC