Guideline 1. Define Use Cases.

When writing specifications it is critical to understand their primary purpose and scope. Clearly defined scope helps to keep the specification content focused and unambiguous.

If the specification describes content requirements (for example, [WCAG10], [UAAG10]), understanding of their purpose is the key to defining the minimal sufficient set. If the specification describes a protocol or Application Programmer Interface (API) -- examples include XML Protocol, DOM -- there should be a clear understanding of the primary use cases. For the purposes of this document, a Use Case is a specification mechanism or technique that captures all the different ways a specification would be used, including the set of interactions between the user and the specification as well as the services, tasks, and functions the specification is required to perform.

Readers of the specification face similar difficulties to writers. To understand what the document says, the reader needs to know the context of the author, and the scenarios the author had in mind. In case of protocols and APIs specifications developers try to assess whether the specifications cover the use cases the product needs to cover. Having no use cases described in the specification generates misuses of the specification itself.

Checkpoint 1.1. Define the scope of the specification. [Priority 1]

This is very basic but powerful requirement. The specification must clearly define what scenarios are in scope and what are out of scope in order to be interpreted, implemented, and tested correctly.

Checkpoint 1.2. Include User Scenarios. [Priority 2]

A User 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 case (e.g., representing each option). Unless otherwise specified, when included in a specification a user scenario is considered to be informative. The specification should have an extensive list of the user scenarios that the authors have in mind. Priorities MAY be assigned to user scenarios, describing how important the particular scenario is for the specification. User scenarios in their turn may help to assess what features are missing and what features are superfluous in the specification.

Checkpoint 1.3. Provide examples. [Priority 1]

[@@revised0819]Illustrate behaviors or requirements in the specification by short and precise examples. The more numerous the examples, the better it is for the specification's comprehensibility. Specifications should illustrate every major feature by example, although the satisfaction of this checkpoint does not impose any specific relationship between examples, on the one hand, and features or requirements.

Checkpoint 1.4. Ensure that every test assertion is covered by an example. [Priority 3]

[@@new0819]Whereas the previous checkpoint can be satisfied by a collection of examples with any relationship to the requirements and behaviors of the specification, this checkpoint requires that there be a mapping from each test assertion in the specification to an example. The relationship of test assertions to examples need not be one-to-one, however examples should be short and precise, for clarity and comprehensibility.

Checkpoint 1.5. Include an interpretation section. [Priority 2]

It is hard to understand the formal descriptions of content without informative interpretations. The recent complex specifications like XML Schema [XML-SCHEMA] and XML Protocol have shown an necessity to have a "Primer" part or section to illustrate how to use the specification. Such a section does not substitute for the numerous examples needed for each requirement or behavior described in the specification, but illustrates how the specification fulfills the User Scenarios.