[EDITOR DRAFT] QA Framework: Specification Examples and Techniques

This document is not a published and official version, it has been just released publically to help for the review with other editors.

W3C Working Draft 15 July 2002

This version:
Latest version:
Previous version:
Karl Dubost (www-qa@w3.org)
Lofton Henderson (www-qa@w3.org)
See Acknowledgments.


This document is part of the of the Quality Assurance (QA) Activity. It presents examples and describes the techniques for writing specifications inside W3C. It complements QA Framework: Specification Guidelines [QAF-SPEC], by specifying or illustrating how to meet the checkpoints for writing a better specification of that document.

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest version of this document series is maintained at the W3C.

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 version is the first public Working Draft, and supersedes all previous WG-only drafts. It is expected that updated WD versions of this document will be produced regularly, along with other members of the Framework documents family. Future progression of this document beyond Working Draft is possible, but has not yet been determined.

In this version, example case studies are presented depending on their ability to illustrate the checkpoint -- how in all W3C specifications the checkpoints of the specifications guidelines [QAF-SPEC] have been implemented. As the specifications predate the QA Specificaton Guidelines, no W3C specifications meet all the specifications checkpoints, and some meet them partially inside a checkpoint.

This version lacks any enumeration of techniques -- what Working Groups must or should do to satisfy the specification guidelines checkpoints, and what constitutes conformance to the checkpoints. This is a significant planned addition in a future version. A future version will also derive a final chapter (after the "Guidelines in action") that will provide a retrospective assessment of the case studies, lessons learned, what was effective, and what was not.

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 obsoleted by other documents at any time. It is inappropriate to use W3C Working Drafts as reference material or to cite them 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.

Table of contents

Here the table of contents.

Review-assignment skeleton for document version:

Front matter

[Overview and summary information, see examples in the review matrix, for what to put here for your specific Guideline type (Ops, Spec, Test).]

[@@Ed: We must define somewhere what does that mean to generate a table of contents entry because we are using it very often. Does that mean: ...]

  1. Having an entry in the General TOC. Like XHTML Mod toc
  2. Having an entry in the Full TOC. like XHTML Mod Full Toc
  3. Sometimes like for XHTML 1.0, the TOC does not contain all the entries :( bad. See 3.1.1 of XHTML 1.0 that you don't find in the toc of XHTML 1.0

[@@Ed: Some concepts need to be clarified like]

  1. What's the notion of modules
  2. What's the notion of level
  3. Redefine the conditionnal nature of Checkpoint for exemple if you don't have module Checkpoint 4.1 P1 you don't have to satisfy checkpoint 4.2, 4.3, etc which are also P1.
  4. You don't necessary know that you will have a future to your specification so the notion of level is not clear.

Guidelines and Checkpoints

Guideline 1. Define user scenarios.

[...per-Guideline summary/overview verbiage goes here...]

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

1.2  Include Use Cases.  [Priority 2]

1.3  Include examples.  [Priority 1]

1.4  Include an interpretation section.  [Priority 2]

Guideline 2. Identify what needs to conform and how.

[...per-Guideline summary/overview verbiage goes here...]

2.1  Identify all classes of product.  [Priority 1]

2.2  For each class of product, define the conformance requirements.  [Priority 1]

2.3  Indicate minimal support requirements.  [Priority 3]

2.4  Identify which of the categories of object are specified in the document as a whole.  [Priority 3]

Guideline 3. Address the use of profiles to divide the specification.

[...per-Guideline summary/overview verbiage goes here...]

3.1  Choose whether or not to have profiles.  [Priority 1]

3.2  If profiles are chosen, ensure that a table of contents entry is generated.  [Priority 1]

3.3  If profiles are chosen, indicate whether or not their use is mandatory for conformance.  [Priority 1]

3.4  If profiles are chosen, define any minimal requirements.  [Priority 2]

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

Guideline 4. Address the use of modules to divide the specification.

[...per-Guideline summary/overview verbiage goes here...]

4.1  Choose whether or not to have modules.  [Priority 1]

4.2  If modules are chosen, ensure that a table of contents entry is generated.  [Priority 1]

4.3  If modules are chosen, indicate any mandatory conditions or constraints on their usage.  [Priority 1]

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

Guideline 5. Specify conformance policy.

[...per-Guideline summary/overview verbiage goes here...]

5.1  Make it clear where there are universal requirements for minimum functionality.  [Priority 1]

5.2  Make it clear when conformance requirements are strict.  [Priority 1]

5.3  Make it clear where requirements stop and product-specific extra features begin.  [Priority 1]

5.4  The conformance clause should contain or refer to the conformance policy.  [Priority 1]

5.5  If special conformance terms are used, include a definition in the specification.  [Priority 1]

Guideline 6. Clarify the relation between deprecated features and conformance.

[...per-Guideline summary/overview verbiage goes here...]

6.1  Identify and clearly indicate each deprecated feature.  [Priority 1]

6.2  For each class of product, specify the level of support required for each deprecated feature and the conformance consequences of the deprecation.  [Priority 1]

6.3  Include an explanation for the deprecation.  [Priority 3]

6.4  Include examples to illustrate how to avoid using deprecated features.  [Priority 3]

6.5  Generate a table of contents entry.  [Priority 2]

Guideline 7. Address the use of levels to divide the specification.

[...per-Guideline summary/overview verbiage goes here...]

7.1  Choose whether or not to have levels.  [Priority 1]

7.2  If levels are chosen, ensure that a table of contents entry is generated.  [Priority 1]

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

Guideline 8. Define discretionary behaviors.

[...per-Guideline summary/overview verbiage goes here...]

8.1  Explicitly state the cases and conditions where discretion is allowed and/or expected.  [Priority 2]

8.2  Indicate implementation dependencies and where applicable address, allowable differences between implementations.  [Priority 1]

8.3  Describe alternative approaches and the conditions under which an implementation is considered to be conforming.  [Priority 1]

8.4  Include a statement regarding consistent handling of a discretionary item within an implementation.  [Priority 2]

8.5  Generate a table of contents entry.  [Priority 2]

Guideline 9. Allow extensions or NOT!

[...per-Guideline summary/overview verbiage goes here...]

9.1  If extensions are disallowed, explicitly state it.  [Priority 3]

9.2  If extensions are allowed, explicitly state it.  [Priority 1]

9.3  If extensions are allowed, make it clear that the extensions do not negate support for required functionality.  [Priority 1]

9.4  If extensions are allowed, use a standard mechanism to define the extension.  [Priority 3]

9.5  If extensions are allowed, register or publish them.  [Priority 3]

9.6  If extensions are allowed, require that implementations include a way to operate without the extension.  [Priority 3]

9.7  Generate a table of contents entry.  [Priority 2]

Guideline 10. Provide a conformance clause.

[...per-Guideline summary/overview verbiage goes here...]

10.1  Include a conformance clause.  [Priority 1]

10.2  Create a separate conformance section.  [Priority 2]

10.3  Generate a conformance clause entry in the table of contents.  [Priority 2]

Guideline 11. Specify how to make conformance claims.

[...per-Guideline summary/overview verbiage goes here...]

11.1  Identify and define all conformance levels or 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]

11.5  Generate a table of contents entry.  [Priority 2]

Guideline 12. Publish an Implementation Conformance Statement proforma.

[...per-Guideline summary/overview verbiage goes here...]

12.1  Include an Implementation Conformance Statement proforma as part of the specification.  [Priority 3]

12.2  Require the ICS be completed as part of the conformance claim.  [Priority 3]

Guideline 13. Support general document conformance conventions.

[...per-Guideline summary/overview verbiage goes here...]

13.1  Use conformance key words.  [Priority 1]

13.2  Distinguish normative and informative text.  [Priority 2]

13.3  Follow Web Accessibility Initiative and Internationalization Guidelines.  [Priority 1]

13.4  Use the same words to express the same ideas.  [Priority 1]

Guideline 14. Use granular grammars to author the specification.

[...per-Guideline summary/overview verbiage goes here...]

14.1  Use W3C endorsed grammar where applicable.  [Priority 1]

14.2  Specify intended behavior in the specification using markup.  [Priority 1]

14.3  Supply prose description of intended behavior together with each test assertion.  [Priority 1]

Guideline 15. Include test assertions.

[...per-Guideline summary/overview verbiage goes here...]

15.1  Supply test assertions in the markup of the specification, if applicable using a set of predefined tags used in the specification markup language.  [Priority 1]

15.2  Tag test assertions according to the above.  [Priority 1]

Back matter

[Optional: opinions, observations, assessment, judgements, etc, about the subject of your review, about the review process, the Guidelines document, etc.]

6. Acknowledgments

The following QA Working Group and Interest Group participants have contributed significantly to the content of this document:

7. References

QA Framework: Specification Guidelines , D. Dimitriadis, L. Henderson, L. Rosenthal, Eds., W3C Working Draft, May 2002, Working Draft companion version to this document, available at [...].
Quality Assurance Interest Group of the W3C QA Activity, which may be found at http://www.w3.org/QA/IG/.
Quality Assurance Working Group of the W3C QA Activity, which may be found at http://www.w3.org/QA/WG/.
Location of all published W3C technical reports, see http://www.w3.org/TR/.