SpecGL: scope rewritten (Guideline 1)

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

regards
Lynne
*****************************
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.

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.

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.

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.

Received on Friday, 17 January 2003 11:04:10 UTC