Techniques for "QA Framework: Specification Guidelines"

Corresponds to Dec 18 SpecGL with modifications to checkpoints that we could remember

1.1	Include the scope of the specification.	[Priority 1]
	Forms of expression such as the following may be used to indicate scope statements: gives rules for, specifies a method of, specifies the characteristics of, specifies the way in which, establishes a systems for Do not include any requirements Create a section called Scope in the beginning of the document
1.2	Illustrate what is in scope.	[Priority 2]
	Explicity list the class of products that are applicable to the specification and elaborate on what each class of product includes, e.g., This specification applies to user agents where user agents includes browsers, multimedia player, and plug-ing. It does not apply to user agents on handheld devices or kiosks. Use easy-to-understand narratives to describe situations that are applicable to the specification Include a list of what is within the scope and include a list of what is outside the scope. Words such as, "This specification is applicable to..." may be used to introduce the examples and/or use cases.
1.3	Provide usage scenarios	[Priority 1]
	Collecting a series of usage scenarios demonstrates the relevance and use of the specification. Provide a description of a context of use of the specification describe the typical operations that the users of the specification may perform and the results that are obtained describe the interrelationship of this technology with other W3C technologies Include a list of use cases in an appendix Link to a separate requirements document that includes describes the relationship of use cases to requirement.
1.4	Provide examples.	[Priority 2]
	Provide an example for each behavior or functionality that was resolved from an Issue Provide an example to illustrate the meaning of abstract notations (e.g., BNF) Provide an example for each chapter in the specification Describes the language features through numerous examples and complement them by references to the normative texts Reference a non-normative tutorial document which includes informative explanation of concepts, behaviour, or functionaility. Provide non-normative references to resources such as books, specification annotation, test sets. These references provide annotations to the specification, pictorial illustrations, and explanations of specification rules.
Guideline 2. Identify what needs to conform and how.
Nbr	Checkpoint	Priority	Yes	No	N/A
2.1	Identify all classes of product.	[Priority 1]
	State what must conform
2.2	For each class of product, define the conformance requirements.	[Priority 1]
	State how the class of product would conform.
2.3	Identify which of the categories of object are specified in the document as a whole.	[Priority 3]

Guideline 3. Specify conformance policy.
Nbr	Checkpoint	Priority	Yes	No	N/A
3.1	Specify any universal requirements for minimum functionality.	[Priority 1]

3.2	Identify strict conformance requirements.	[Priority 1]
	Moot - this has been moved
3.3	Distinguish requirements from product-specific extra features	[Priority 1]
	Moot - this has been deleted
3.4	If special conformance terms are used, include a definition in the specification.	[Priority 1]
	Put definition of conformance terms in the glossary or teminology section of the document
Guideline 4. Address the use of profiles to divide the technology.
Nbr	Checkpoint	Priority	Yes	No	N/A
4.1	Indicate whether or not the use of profiles is mandatory for conformance.	[Priority 1]
	Provide a list of defined profiles with a short description Ensure that the reader understands when a profile is required for conformance: include the name of the profile, a list of the classes of products that fall within the purview of the profile, indicate whether the class of product is required to use the profile for conformance. Ensure that the reader is aware that there are no profiles: provide an explicit statement in the conformance section or indicate there are no profiles on a Conformance Implementation Statement (ISC)
4.2	If profiles are chosen, define any minimal requirements.	[Priority 2]
	This may be accomplished by using a table to present a list of each element (in the profile) and the minimum support required for that element or the latitude allowed by the profile for that element Use the profile to: identify elements, attributies, options and their values, etc. that are applicable to the profile give meaning to implementation dependent semantics of some elements specify subsets or groupings of related items prohibit the use of specific elements, attributes or values
4.3	If profiles are chosen, define their relationships and interaction with other dimensions of variability.	[Priority 2]

4.4	If profiles are chosen, address rules for profiles.	[Priority 2]
	Create a section to explicitly address how a community would specify a valid profile and any restraints. Provide general criteria for the technical content of the profile: a profile must not specify requirements that violate the Recommendation a profile must place requirements on the Recommendation and not on the internal behavior, structure or performance of implementations a profile may contain requirements on the funcational characteristics of implementations claiming conformance to the profile a profile must be consistent in its requirements with respect to its parent Recommendation (if the Recommendation limits the values of an attribute, then the profile can not exceed those limits) a profile must not specify requirements which are conflicting with its parent Recommendation. Include a set of tables (supplemented by descriptive materials) which form a template for writing profiles. The profile rules are inherent in the structure of the tables (e.g., the table requires certain information to be completed -- each such case is a statement equivalent to the rule "Profile must specify ...") Group the set of tables with the rules that apply to all profiles, those rules that apply to only a specific class of product, and those rules that apply across a functional grouping. Provide a rule for each element defined in the Recommendation - each rule specifies whether a profile must address the rule, whether a profile may optionally address the rule, or whether the profile must not restrict the use of the element in any manner.
Guideline 5. Address the use of modules to divide the technology.
Nbr	Checkpoint	Priority	Yes	No	N/A
5.1	If modules are chosen, indicate any mandatory conditions or constraints on their usage.	[Priority 1]

5.2	If modules are chosen, define their relationships and interaction with other dimensions of variability.	[Priority 2]

Guideline 6. Address the use of functional levels to divide the technology.
Nbr	Checkpoint	Priority	Yes	No	N/A
6.1	If levels are used, define their relationships and interaction with other dimensions of variability.	[Priority 2]


Guideline 7. Identify the relation between deprecated features and conformance.
Nbr	Checkpoint	Priority	Yes	No	N/A
7.1	Identify each deprecated feature.	[Priority 1]
	Include a normative section that lists the deprecated features Tag each deprecated feature - this allows it to be extracted into another document, indexed, etc.
7.2	For each class of product, specify the degree of support required for each deprecated feature and the conformance consequences of the deprecation.	[Priority 1]
	Include a normative table that lists each deprecated feature and whether or not it must be implemented by the class of product.
7.3	Include an explanation for the deprecation.	[Priority 3]

7.4	Include examples to illustrate how to avoid using deprecated features.	[Priority 3]
	Provide alternative ways to implement the feature
Guideline 8. Define discretionary items.
Nbr	Checkpoint	Priority	Yes	No	N/A
8.1	State the circumstances for when discretionary items are allowed	[Priority 1]
	Include a normative section listing all discretionary items Tag each deprecated feature - this allows it to be extracted into another document, indexed, put into a TOC, etc.
8.2	For implementation dependencies, address the allowable differences between implementations	[Priority 1]

8.3	Indicate any constraints on the number of choices/options that can be implemented	[Priority 2]
	For each discretionary item, state whether an implementation can do: none of the choices/options, one and only one choice/option, or any number of choices/options.
8.4	Promote uniform policy of discretionary choices.	[Priority 2]

Guideline 9. Allow extensions or NOT!
Nbr	Checkpoint	Priority	Yes	No	N/A
9.1	Indicate if the specification is extensible	[Priority 1]
	In the conformance section, include a section called Extensibility which describes the conditions under which the specification can be extended. In the conformance section, for applicable DoV or in reference to a specific part of the specfiication, explicitly make a statement that extensions are not allowed. Create a chapter called Extensions and put all information related to extensions, e.g., conformance restraints, applicability to various DoV, etc., in this chapter.
9.2	if extensions are allowed, define their scope and constraints	[Priority 1]

9.3	Prevent extensions from contradicting the specification.	[Priority 1]

9.4	Define a uniform mechanism to create the extension.	[Priority 3]
	Signal that an extension will follow by using a special character(s) or namespace
9.5	Require that extensions be published.	[Priority 3]
	Provide web space that contains a list of extensions, each with a genearl description and a functional description (their syntax and semantics)
9.6	Require implementations to include a way to "turn off" extensions.	[Priority 3]

Guideline 10. Provide a conformance clause.
Nbr	Checkpoint	Priority	Yes	No	N/A
10.1	Include a conformance clause.	[Priority 1]

10.2	Make normative reference to specifications on which the current specification depends	[Priority 2]
	Include a section, "References (normative)" that lists specification on which the current specification depends.
Guideline 11. Specify how to make conformance claims.
Nbr	Checkpoint	Priority	Yes	No	N/A
11.1	Identify and define all conformance designations.	[Priority 1]

11.2	Provide specific wording of the claim.	[Priority 3]

11.3	Provide a conformance disclaimer.	[Priority 3]

11.4	Impose no restrictions about who can make a claim or where claims can be published.	[Priority 1]

Guideline 12. Publish an Implementation Conformance Statement proforma.
Nbr	Checkpoint	Priority	Yes	No	N/A
12.1	Provide an Implementation Conformance Statement proforma.	[Priority 3]
	Create a set of tables which are a template of all the checkpoints in the Guideline with a column in which the user can indicate if a checkpoint is satisfied, not satisfied, or not applicable. Create a set of tables which are a template for every function in the specification.
12.2	Require the ICS be completed as part of the conformance claim.	[Priority 3]

Guideline 13. Support general document conformance conventions.
Nbr	Checkpoint	Priority	Yes	No	N/A
13.1	Use conformance key words.	[Priority 1]

13.2	Distinguish normative and informative text.	[Priority 1]

13.3	Use consistent terminology.	[Priority 1]

13.4	Provide a fast way to find conformance information	[Priority 2]
	Include a Table of Contents which would include the conformance section and all conformance-related sections Include an index for all conformance-related topics
Guideline 14. Provide test assertions.
Nbr	Checkpoint	Priority	Yes	No	N/A
14.1	Provide test assertions	[Priority 1]
	Develop a document to include a list of test assertions. This document may be a test specification or assertion specification. Tag each requirement in the specification.
14.2	Provide a mapping between the specification and the test assertions list	[Priority 2]