Re: SpecGL: scope rewritten (Guideline 1)

I think this is an improvement.  It starts to sort out some of the 
confusion about what is a scope definition, and helps draw the distinction 
between defining the scope and illustrating the scope.

I have a couple of suggestions and clarification issues:

At 10:55 AM 1/17/2003 -0500, Lynne Rosenthal wrote:

>In Seattle, discussions of AR-002 regarding scope resulting in the 
>acknowledgement that the Guideline needed to be clarified.  Based on what 
>I heard, taking some words from ISO -below is a suggested rewrite of GL 1.
>
>Also: I don't know where to put this statement, but think it would be good 
>to add. It applies to use cases, usage scenarios and examples.
>"Use cases (Usage Scenarios, examples)  do no contain provisions to which 
>it is necessary to conform in order to be able to claim conformance with 
>the specification. "

In other words, they are "informative".  Given that we have a checkpoint 
about using consistent terminology (into which I implicitly read, "use 
terminology consistently"), and given that we require to distinguish 
"normative and informative", IMO the sentence should contain the word 
"informative".

>[...]
>*****************************
>Guideline 1.  Define Scope
>
>1.1  Include the scope of the specification [P1]
>
>The scope describes the areas covered by the specification, thereby 
>indicating the limits of applicability of the specification or particular 
>parts of it.  It does not specify requirements and is worded as a series 
>of statements of fact.
>
>To fulfill this checkpoint, a specification MUST define without ambiguity 
>the subject matter of the specification, MUST identify the applicable 
>classes of products, and SHOULD include a statement of objectives and/or 
>goals. This information MUST appear at the beginning of the document.

Doesn't the second MUST replicate the requirements of CP2.1?  If you agree, 
then I suggest that it be removed and in a "Discussion." paragraph include 
a forward reference to CP2.1, with some explanation like "...there are 
other checkpoints and requirements which are closely related to defining 
the scope.  See CP2.1, for example."

Btw, it is my belief that we will have a second Last Call, and I think that 
a major part of it will be to take the set of requirements that we 
currently have encapsulated (which IMO is mostly right and complete), and 
re-sort or repackage them amongst guidelines.  Unless we want to risk 
significant delay to LC, I suggest that we NOT try to get into too much of 
this (re-sort and repackage) before LC, in our single remaining (regular) 
telecon.

The WG would probably be happy to consider complete and completely drafted 
proposals for change (like this one).  But what we don't have time for now 
is invention on the fly -- trying to invent significant revisions in our 
last, close-all-issues telecon.  Or trying to sort out new issues that 
aren't accompanied by complete alternate text.  (This is another way of 
saying, the comment period for raising new issues for this revision and 
production of LC text is CLOSED.)


>Rationale: it helps the writer and the reader know the limits of what is 
>specified in a normative document.  It provides the reader with how the 
>specification could be used and by whom.
>
>1.2  Illustrate what is in scope [P2]
>
>To fulfill this checkpoint, a specification MUST include examples or use 
>cases illustrating what is in or out of scope.

I'm unsure that we're saying what we intend.  Specifically, I want to 
question the two occurrences of "or".

"...what is in or out of scope".  Literally, doesn't this mean that the 
checkpoint could be satisfied by only including out-of-scope examples or 
use cases?  Is that what we intend?  As I recall, the discussion was 
leaning towards MUST for in-scope, something else (SHOULD or MAY) for 
out-of-scope.

"...examples or use cases".  Again, this means that it could be satisfied by:

** only examples
** only use cases
** both.

Which option do we intend?


>Rationale:  examples and use cases give the reader additional information 
>in understanding the purpose , audience, and applicability of the 
>specification.
>
>1.3  Provide Usage Scenarios [P3]
>
>A Usage Scenario is an instance of a use case, representing a single path 
>through the use case.  Thus, there may be a scenario for the main flow 
>through the use case and other scenarios for each possible variation of 
>flow through the use cases (e.g., representing each option).
>
>To fulfill this checkpoint, a specification MUST include or link to Usage 
>Scenarios.
>
>Rationale: usage scenarios provide more specific information regarding the 
>authors' view of the specification's applicability.  The additional 
>information given in a usage scenario assists the understanding or use of 
>the specification.
>
>
>1.4 Provide examples. [P2] (@@I think we decided to combine 1.3 and 
>1.4  here is a suggested combination)
>
>To fulfill this checkpoint, a specification MUST include or link to at 
>least one example.

I sympathesize with Alex's comment, "example of what?".  To distinguish 
this better from CP1.2, I suggest to replace "at least one example" with 
"one or more examples of the functionality, concepts, and behaviors of the 
specification."


>Rationale: it is difficult to understand some concepts, behavior, or 
>functionality without informative interpretations.  Providing examples for 
>behavior or concepts that are either innately complex or for which the WG 
>have had to explain to its members or the public, aids the reader in 
>interpreting the specification.

-Lofton.

Received on Monday, 20 January 2003 10:55:02 UTC