QA Specification Guidelines - Implementation Conformance Statement

This version:: http://www.w3.org/TR/2004/WD-qaframe-spec-20040830/specgl-ics
This document is an appendix to:: http://www.w3.org/TR/2004/WD-qaframe-spec-20040830/
Latest version of "QA Framework: Specification Guidelines":: http://www.w3.org/TR/qaframe-spec/
Editors:: Karl Dubost, W3C; Lynne Rosenthal, NIST; Dominique Hazaël-Massieux, W3C; Lofton Henderson, CGM Open
Contributors:: See Acknowledgments in QA Framework: Specification Guidelines.

Abstract

This document is an appendix QA Framework: Specification Guidelines [QAF-SPEC]. It provides a tabular checklist of all principles and good practices from the specification guidelines, sorted by topics. Please refer to QA Framework: Specification Guidelines [QAF-SPEC] for the full statement and description of the specification principles and good practices, as well as references to related documents and full credits and acknowledgements of contributors to the specification guidelines work.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document is a W3C Working Draft (WD), made available by the W3C Quality Assurance (QA) Activity for discussion by W3C members and other interested parties. For more information about the QA Activity, please see the QA Activity statement.

This document is derived from and is an appendix to QA Framework: Specification Guidelines [QAF-SPEC], which document is a W3C Working Draft, made available by the W3C Quality Assurance (QA) Activity for discussion by W3C members and other interested parties. For more information about the QA Activity, please see the QA Activity statement. Please see the "Status of this document" section of the corresponding specification guidelines [QAF-SPEC], for complete details about the status of the specification guidelines version from which this is extracted and which it accompanies.

Please send comments to www-qa@w3.org, the publicly archived list of the QA Interest Group [QAIG]. Please note that any mail sent to this list will be publicly archived and available. Do not send information you wouldn't want to see distributed, such as private data.

Publication of this document does not imply endorsement by the W3C, its membership or its staff. This is a draft document and may be updated, replaced, or made obsolete by other documents at any time. It is inappropriate to use this document as reference material or to cite it as other than "work in progress".

A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR.

Introduction

This checklist includes all defined principles and good practices from the QA Framework: Specification Guidelines [QAF-SPEC] presented in a tabular format. The principles and good practices are presented by order of their topics.

The presentation is intended to be convenient for organizers and evaluators of QA projects in W3C Working Groups, to facilitate assessing specifications against the checkpoints. The table includes spaces for scoring each checkpoint, "yes" (satisfied), "no" (not satisfied), "n/a" (not applicable).

Checklist table

Guidelines	YES	NO	N/A
A. Specifying Conformance
A.1. A conformance clause is essential
Principle: Include a conformance clause.
Good Practice: Define the specification conformance model in the conformance clause
Good Practice: Specify in the conformance clause how to distinguish normative from informative content.
A.2 Specify how to make conformance claims
Good Practice: Provide the wording for conformance claims.
Good Practice: Provide an Implementation Conformance Statement (ICS) proforma.
Good Practice: Require an Implementation Conformance Statement (ICS) as part of valid conformance claims.
B. The Nature of the Specification
B.1. Scope
Principle: Define the scope
Good Practice: Write simple, direct statements in the scope.
Good Practice: Use examples or use cases to illustrate
B.2 What needs to conform
Principle: Identify who or what will implement the specification
B.3 Make a list of normative (and non-normative) references
C. Pieces needed to Specify Conformance
C.1 Define your terms
Principle: Define the terms used in the normative parts of the specification
Principle: Create conformance labels for each part of the conformance model
Good Practice: define the terms in-line, and consolidate the definitions in a glossary section
Good Practice: Re-use existing terms, and don't redefine them
C.2 What is mandatory
Principle: Use a consistent style for conformance requirements and explain how to distinguish them
Principle: Explain which conformance requirements are mandatory, which are suggested and which are optional
D. Managing Variability
D.1 Subdivide
Good Practice: Subdivide the technology to foster implementation
Principle: If the technology is subdivided, then indicate which subdivisions are mandatory for conformance
Principle: If the technology is subdivided, then address subdivision conditions or constraints
Good Practice: Define rules for creating profiles
D.2 Optionality and Options
Good Practice: Determine the need for each option. Make sure there is a real need for the option.
Good Practice: Indicate any limitations or constraints
Good Practice: Address the impact of the option
Good Practice: Make options easy to find. Use tags to label options.
D.3 Extensibility and Extensions
Principle: Address the extensibility topic inside specification.
Good Practice: Define the extension mechanism
Principle: Prevent extensions from breaking conformance
Good Practice: Define error handling for unknown extensions.
D.4 Deprecation
Principle: Identify each deprecated feature.
Principle: Define how to handle each deprecated feature
Good Practice: Explain how to avoid using a deprecated feature
Good Practice: Identify obsolete features
Good Practice: Define an error handling mechanism
E. Do Quality Control
Principle: Do quality control during the specification development.
Good Practice: Do a systematic and thorough review.
Good Practice: Write sample code or tests.
Good Practice: Write Test Assertions.

References

QAF-SPEC: QA Framework: Specification Guidelines, Karl Dubost, Lynne Rosenthal, Dominique Hazaël-Massieux, Lofton Henderson, W3C Working Draft, 30 August 2004, http://www.w3.org/TR/2004/WD-qaframe-spec-20040830/ .Latest version available at http://www.w3.org/TR/qaframe-spec/ .