QA Framework: Specification Examples and Techniques

W3C Working Group Note 12 September 2003

This version:: http://www.w3.org/QA/WG/2003/09/qaframe-spec-extech-20030912
Latest version:: http://www.w3.org/QA/WG/qaframe-spec-extech
Previous version:: http://www.w3.org/QA/WG/2003/02/qaframe-spec-extech-20030203
Editors:: Karl Dubost, W3C (www-qa@w3.org); Lofton Henderson, CGM Open; Lynne Rosenthal, NIST
Contributors:: See Acknowledgments.

Abstract

This document is part of the of the Quality Assurance (QA) Activity. It presents examples and describes the techniques of producing specifications (Technical Reports) that are clearer, more implementable, and better testable. It complements QA Framework: Specification Guidelines [QAF-SPEC], illustrating how specification authors and Working Groups might meet the specification guidelines and checkpoints of that document.

Status of this document

This version is a QA Working Group (QAWG) editor's draft, to accompany the 20030912 QAWG editor's CR draft of Specification Guidelines (SpecGL). Editorial alignment with revised SpecGL is still incomplete.

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 Note, made available by the W3C Quality Assurance (QA) Activity for discussion by W3C members and other interested parties. The document status is being maintained as a W3C Note, pursuant to resolution of Issue #68. For more information about the QA Activity, please see the QA Activity statement.

This draft differs from the Previous Version, by incorporating changes to wording, order, and statements of guidelines and checkpoints that have been made to SpecGL as a result of Last Call issue processing. Revision of the corresponding Examples&Techniques content itself is still in progress. The principal changes from the Previous Version are listed in the "Change history" section.

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. For each guidelines we will separate the examples from the techniques in two different sections.

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.

Introduction
Rationale for these techniques and examples
Specification guidelines in action
1. Guideline 1. Define Scope.
2. Guideline 2. Identify what needs to conform and how.
3. Guideline 3. Address the use of profiles, modules and levels to divide the technology.
4. Guideline 4. Identify the relation between deprecated features and conformance.
5. Guideline 5. Define discretionary items.
6. Guideline 6. Allow extensions or NOT!
7. Guideline 7. Clearly identify conformance requirements.
8. Guideline 8. Document the conformance policy.
9. Guideline 9. Specify how to make conformance claims.
10. Guideline 10. Provide test assertions.
Conformance
Acknowledgments
References
Change history

Introduction

You will be able to find a previous public version of this document which was synchronized with the QA Specification Guidelines at that time. QA Specification Guidelines WD has been modified and this version is the result of these modifications. There is still a lot of work to do in this document.

Rationale

@@to write text here@@

Specification guidelines in action

This section looks at each of the guidelines and checkpoints in the specification guidelines [QAF-SPEC ]. For each checkpoint, there are two sections of content:

Examples
Techniques

The Examples section demonstrates how the checkpoints has been applied in the past in previous W3C specifications. The Techniques section show possible solution to fullfil the checkpoint. The given techniques are not necessary the only one possible.

The structure of this chapter exactly parallels the structure of the its Chapter 3, "Guidelines", of the Specification Guidelines [QAF-SPEC] document -- each checkpoint in this section links back to the corresponding checkpoint of QA Framework: Specification Guidelines [QAF-SPEC].

Guideline 1. Define Scope.

Checkpoint 1.1 Include a scope statement. [Priority 1]

Examples

@@examples include XML Protocol, DOM@@
XML Base. The XML Base introduction defines clearly what are the scenarios in scope of the specification. It defines what the document describes : a mechanism for providing base URI services to XLink, ... and it defines that the range of applications that will be implied by this specification : Applications and specifications built upon these new technologies [XLink and XML Infoset] will natively support XML Base.
DOM Level 1. The DOM Level 1 introduction defines in a short sentence what the specification is : The Document Object Model (DOM) is an application programming interface (API) for HTML and XML documents. The introduction is articulated around an overview of the technology, a section on what the DOM is and section on what the DOM is not. it also gives a bit of historical context to understand why this technology has arised.

Techniques

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

Checkpoint 1.2 Illustrate scope. [Priority 2]

Examples

(Under Construction)

Techniques

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.

Checkpoint 1.3 Illustrate functional details. [Priority 2]

Examples

SVG. For each element of the SVG specification, you will have the verbose definition of the element, the DTD definition, the attribute definitions and an example. For example, in the definition of the element rect, you will find precise examples with the markup to generate the rect, a rendering of this markup as an image to help people to visualize what it should be and an original version of the markup to test it as a separate file.
HTML 4.01. The HTML 4.01 specification has been designed in a very educative way. It has strong caveats with regards to the implementability and the definition of testability. But by its design, the specification has very good examples. An important thing that you must say when you give an example is whether or not the rendering of the example is mandatory. Many developpers try to mockup a rendered example when a specific rendering is not mandatory.

When HTML 4.01 defines the elements strong and em and gives examples of it, it clearly says that The presentation of phrase elements depends on the user agent. Generally, visual user agents present EM text in italics and STRONG text in bold font. Speech synthesizer user agents may change the synthesis parameters, such as volume, pitch and rate accordingly. It would have even be better to mention that user agents should not assume specific rendering for these elements.

Techniques

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.

Checkpoint 2.1 Identify all classes of product. [Priority 1]

Examples

Ruby. The conformance section of Ruby is very explicit and detailed about classes of product. For each of these classes, Ruby conformance section defines a set of rules, the implementers or the users must respect. It defines rules for markup, dtd, document, module, generator, interpreter.
XHTML Modularization. The Conformance Definition of this specification introduces also classes of product and defines the conformance for each of these classes.
Schema Part 1 could be said to define an abstract notion of "schema validity" but this checkpoint can only be satisfied if the Recommendation says explicitly whether it is setting expectations of an XML parser or of a "schema validator" that could be stand-alone.

Schema Part 2 defines data types, so it is a specification of type 2 above — content/data — and it is used as a foundation by other specifications (e.g., XPath 2.0) as well as being part of the schema validator and hence parser requirements. The specification could define the behavior of a data-input tool that rejects data not fitting the schema, but it probably would not because the tool would be expected to use a parser module to validate the data. To satisfy this checkpoint, the Schema Part 2 specification has to make clear whether it is to be taken as an independent specification of a parser (that produces data from arbitrary strings) or a foundation to be used by other specifications.

Techniques

State what must conform.

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

Examples

Ruby. See checkpoint 2.1 @@Have to find other examples@@
XHML Modularization defines for each particular class of products the conditions of conformance covered by this class: XHTML Host Language Document Type, XHTML Integration Set Document, XHTML Family Module, XHTML Family Document, XHTML Family User Agent.

For example the XHTML Host Language Document Type defines conformance criterias articulated in 5 points which explained the way a DTD must be modified to accept extensions. It also defines this family of document type as "XHTML Host Language Conforming".
XPath (XML Path Language 1.0, [XPATH10]) relies on specifications that use XPath — such as XPointer (XML Pointer Language, [XPOINTER]) and XSLT (XSL Transformations 1.0, [XSLT10]) — to specify criteria for conformance of implementations of XPath.

Techniques

State how the class of product would conform.

Checkpoint 2.3 Identify the applicable specification categories. [Priority 3]

Examples

XHTML Basic. In in the introductory part of XHTML Basic, the specification defines clearly the field of application of the technology. The whole section 1.1. XHTML for Small Information Appliances explains why it has been created and designed.
With the release of the SVG 1.1 Specification, two profiles for Mobile and basic implementations have been defined: Mobile SVG Profiles: SVG Tiny and SVG Basic. The introductory part defines the categories of object covered by this specification: Because of the low memory, low CPU power and limited display of mobile devices, Mobile SVG profiles introduce constraints on content, attribute types, properties, and user agent behavior. This section describes these constraints and design rationale behind them.

Techniques

(Under Construction)

Checkpoint 2.4 If there are several classes of products, define their relationships and interaction with other dimensions of variability. [Priority 2]

Examples

(Under Construction)

Techniques

(Under Construction)

Guideline 3. Address the use of profiles, modules and levels to divide the technology.

Checkpoint 3.1 Indicate whether or not the use of profiles is mandatory for conformance. [Priority 1]

Examples

Mobile SVG Profiles defines user agents as SVG Tiny User Agent if it's User Agent that requires only the facilities described as mandatory in this specification. A list of the criteria, that the User Agent must meet, is given just after.

Techniques

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)

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

Examples

CSS TV Profile 1.0. The conformance section of the CSS TV profile defines the requirements for each class of product.

Techniques

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

Checkpoint 3.3 If profiles are chosen, address rules for profiles. [Priority 2]

Examples

SMIL 2.0 defines the requirements on identifiers for SMIL Host Language Conformant Languages Profiles. The language profile is specified through its DTD or XML Schema. So the specification defines a set of rules: a default namespace, the way the namespace must be declared with constraints on it. It also gives hints which helps to create a DTD for a Language Profile.

Techniques

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.

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

Examples

DOM Level 2. The specification is articulated around modules all these modules contain a set of feature. The specification defines that an implementation is DOM Level 2 conformant if it supports the Core module defined in this document. An implementation conforms to a DOM Level 2 module if it supports all the interfaces for that module and the associated semantics. an defined a minimal requirement in the section Fundamental Interfaces, stating that Any implementation that conforms to DOM Level 2 or a DOM Level 2 module must conform to the Core module.. So at least you must have the DOM Level 2 Core module.

Techniques

(Under Construction)

Checkpoint 3.5 If profiles, modules or levels are used, define their relationships and interaction with other dimensions of variability. [Priority 2]

Examples

CSS TV Profile 1.0.
SMIL 2.0.
XHTML Modularization. When you decide to implement the Intrinsic Events Module, a table gives the list of all elements that are affected by this module and says The attributes indicated in the following table are added to the attribute set for their respective elements only when the modules defining those elements are selected.

Techniques

(Under Construction)

Guideline 4. Identify the relation between deprecated features and conformance.

Checkpoint 4.1 Identify each deprecated feature. [Priority 1]

Examples

XHTML 1.1. The specification defines the modules that are part of the specification, but clearly identify the Style Attribute Module as Deprecated.
HTML 4.01. The specification has two tables which summarize the list of elements and list of attributes. When a element of the index of HTML elements is deprecated, it is clearly indentified as it. It also the case for the index of attributes.
XHTML Modularization. In this specification, the Name Identification Module has been completely deprecated as a whole and at the begining of the section it's written This module is deprecated.

Techniques

Include a normative section that lists the deprecated features
Tag each deprecated feature - this allows it to be extracted into another document, indexed, etc.

Checkpoint 4.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]

Examples

MathML 2.0. The specification defines the deprecated features of MathML 1.0 and says that authoring tools, for example, may not generate MathML markup containing deprecated features
HTML 4.01. The specification defines the notion of deprecated with regards to HTML 4.01 and defines how user agents should handle them.

Techniques

Include a normative table that lists each deprecated feature and whether or not it must be implemented by the class of product.

Checkpoint 4.3 If deprecated features exist, define their relationships and interaction with other dimensions of variability. [Priority 2]

Examples

(Under Construction)

Techniques

(Under Construction)

Checkpoint 4.4 Include an explanation for the deprecation. [Priority 3]

Examples

HTML 4.01. The specification defines the word deprecated with regards to HTML 4.01.
MathML 2.0. defines the deprecation as MathML 2.0 contains a number of MathML 1.x features which are now deprecated. The following points define what it means for a feature to be deprecated, and clarify the relation between deprecated features and MathML 2.0 compliance. A lost of 3 points follows and explains what must be the behaviour of tools with regards to the deprecation.

Techniques

Provide alternative ways to implement the feature

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

Examples

HTML 4.01. In HTML 4.01, the element applet has been deprecated with all its attributes in favor of object. The specification gives a deprecated example of markup and gives also its equivalent with the use of the element object.

Techniques

(Under Construction)

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

Examples

(Under Construction)

Techniques

(Under Construction)

Guideline 5. Define discretionary items.

Checkpoint 5.1 State the circumstances for when discretionary items are allowed [Priority 1]

Examples

CSS Level 1. There's a mechanism in CSS 1 to define the balance between author and reader and the way they can influence the presentation through the style sheet. The specification says explicitely about the cascade The UA is free to choose the mechanism for referencing personal style sheets. and describes the potential conflicts that could arise in such mechanisms.

Techniques

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.

Checkpoint 5.2 For implementation dependent values or features, address the allowable differences between implementations. [Priority 1]

Examples

CSS Level 1. There's a mechanism in CSS 1 to define the balance between author and reader and the way they can influence the presentation through the style sheet. The specification says explicitely about the cascade The UA is free to choose the mechanism for referencing personal style sheets. and describes the potential conflicts that could arise in such mechanisms.
HTML 4.01. There's a mechanism to specify the character encoding of a document which may be displayed in various way depending on how it has been written, how it has been delivered, and how the user agent is reading it. There are dependencies between these three levels of interaction. The HTML 4.01 specification describes these dependencies and for example, says for user agents that may provide a mechanism that allows users to override incorrect "charset" information..

Techniques

(Under Construction)

Checkpoint 5.3 Indicate any constraints on the number of choices/options that can be implemented for discretionary choices [Priority 2]

Examples

HTML 4.01. The mechanism to specify the character encoding of a document defines the priorities for a user agent to determine the document's character encoding from highest priority to lowest.
1. An HTTP "charset" parameter in a "Content-Type" field.
2. A META declaration with "http-equiv" set to "Content-Type" and a value set for "charset".
3. The charset attribute set on an element that designates an external resource.

Techniques

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.

Checkpoint 5.4 Promote consistent handling of discretionary choices. [Priority 2]

Examples

@@more a technique than an example, or if you have an example tell me.@@

Techniques

(Under Construction)

Checkpoint 5.5 If discretionary items are used, define their relationships and interaction with other dimensions of variability. [Priority 2]

Examples

(Under Construction)

Techniques

(Under Construction)

Guideline 6. Allow extensions or NOT!

Checkpoint 6.1 Indicate if the specification is extensible. [Priority 1]

Examples

(Under Construction)

Techniques

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.

Checkpoint 6.2 Prevent extensions from contradicting the specification. [Priority 1]

Examples

(Under Construction)

Techniques

(Under Construction)

Checkpoint 6.3 Define a uniform mechanism to create an extension. [Priority 3]

Examples

XHTML Modularization. The mechanism to define and extend module is clearly defined in XHTML Modularization. The specification addresses all level of extensibility and the method to create these extensions. An informative appendix gives examples and methods to do it.

Techniques

Signal that an extension will follow by using a special character(s) or namespace

Checkpoint 6.4 Require that extensions be published. [Priority 3]

Examples

(Under Construction)

Techniques

Provide web space that contains a list of extensions, each with a general description and a functional description (their syntax and semantics)

Checkpoint 6.5 Mitigate the impact of extensions on interoperability. [Priority 3]

Examples

(Under Construction)

Techniques

(Under Construction)

Checkpoint 6.6 If extensions are allowed, define their relationships and interaction with other dimensions of variability. [Priority 2]

Examples

(Under Construction)

Techniques

(Under Construction)

Guideline 7. Clearly identify conformance requirements.

Checkpoint 7.1 Use conformance key words. [Priority 1]

Examples

XHTML 1.1. The conformance section of XHTML 1.1 uses the the RFC 2119 key words: The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

Techniques

(Under Construction)

Checkpoint 7.2 Distinguish normative and informative text. [Priority 1]

Examples

XHTML 1.1. The differences between normative and informative part are clearly identify in this specification. After each local table of contents or a specific entry, it is written This section/appendix is normative or This section/appendix is informative.

Techniques

(Under Construction)

Checkpoint 7.3 Use consistent terminology. [Priority 1]

Examples

(Under Construction)

Techniques

(Under Construction)

Checkpoint 7.4 Provide a fast way to find conformance information [Priority 2]

Examples

(Under Construction)

Techniques

Include a Table of Contents which would include the conformance section and all conformance-related sections
Include an index for all conformance-related topics

Checkpoint 7.5 Make normative reference to specifications on which the current specification depends [Priority 1]

Examples

Ruby Annotation gives a list of all the specifications which are normative for Ruby itself. Editors are encouraged to separate normative references and informative references.

Techniques

Include a section, "References (normative)" that lists specification on which the current specification depends.

Guideline 8. Document the conformance policy.

Checkpoint 8.1 Specify any universal requirements for minimum functionality. [Priority 2]

Examples

DOM Level 2. The specification is articulated around modules all these modules contain a set of feature. The specification defines that an implementation is DOM Level 2 conformant if it supports the Core module defined in this document. An implementation conforms to a DOM Level 2 module if it supports all the interfaces for that module and the associated semantics. an defined a minimal requirement in the section Fundamental Interfaces, stating that Any implementation that conforms to DOM Level 2 or a DOM Level 2 module must conform to the Core module.. So at least you must have the DOM Level 2 Core module.
XHTML Modularization. In the conformance section of Modularization of XHTML, the minimum requirements are clearly defined. For example in the section XHTML Host Language Document Type Conformance, the third list item of conformance criteria defines : The DTD which defines the document type must include, at a minimum, the Structure, Hypertext, Text, and List modules defined in this specification.

Techniques

(Under Construction)

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

Examples

UAAG 1.0. This specification defines the notion of conformance profiles. Each terms used are defined and completely explicited with regards to the specification itself. For example:
A conformance profile is a list of assertions that identify:
1. a version of UAAG 1.0,
2. a set of requirements in that document, and
3. a list of specifications implemented to satisfy some of those requirements.

Techniques

Put definition of conformance terms in the glossary or terminology section of the document

Checkpoint 8.3 Justify any usage of a dimension of variability. [Priority 1]

Examples

(Under Construction)

Techniques

(Under Construction)

Checkpoint 8.4 Include a conformance section. [Priority 1]

Examples

Example in DOM Level 2 Core

Techniques

(Under Construction)

Checkpoint 8.5 Identify and define all conformance designations. [Priority 1]

Examples

WCAG 1.0. The WAI has defined for the WCAG 3 levels of conformance. The conformance section describes and names the three levels and what must be respected for each leveal.

Techniques

(Under Construction)

Guideline 9. Specify how to make conformance claims.

Checkpoint 9.1 Provide specific wording of the claim. [Priority 3]

Examples

WCAG 1.0. In the definition of the 3 levels of WCAG conformance, there's a mandatory way of expressing the claim : Claims of conformance to this document must use one of the following two forms. followed by the description of the two forms.

Techniques

(Under Construction)

Checkpoint 9.2 Provide a conformance disclaimer. [Priority 3]

Examples

ATAG 1.0. In the definition of the ATAG 1.0 conformance, there's a disclaimer for people who wish to claim their conformance: Claimants are solely responsible for their claims and the use of the conformance icons. If the subject of the claim (i.e., the software) changes after the date of the claim, the claimant is responsible for updating the claim. Claimants are encouraged to conform to the most recent guidelines available.

Techniques

(Under Construction)

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

Examples

ATAG 1.0. The conformance section of ATAG 1.0 gives an overview of the people who can claim their conformance Anyone may make a claim (e.g., vendors about their own products, third parties about those products, journalists about products, etc.). Claims may be published anywhere (e.g., on the Web or in product documentation).

Techniques

(Under Construction)

Checkpoint 9.4 Provide an Implementation Conformance Statement proforma. [Priority 3]

Examples

UAAG 1.0 explains how User Agent can claim conformance and gives a sample of this Conformance Statement.

Techniques

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.

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

Examples

(Under Construction)

Techniques

(Under Construction)

Guideline 10. Provide test assertions.

Checkpoint 10.1 Provide test assertions [Priority 2]

Examples

(Under Construction)

Techniques

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.

Checkpoint 10.2 Provide a mapping between the specification and the test assertions list [Priority 2]

Examples

(Under Construction)

Techniques

(Under Construction)

Conformance

There is no concept of conformance to this document. Rather, conformance is measured relative to the checkpoints of the companion document, QA Framework: Specification Guidelines [QAF-SPEC]. This document relates real-world examples to the checkpoints' requirements, and also presents techniques by which the checkpoints may be satisfied. In that sense, it defines conformance criteria for the conformance requirements (checkpoints) of the operational guidelines document.

Acknowledgments

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

Daniel Dardailler (W3C)
Dimitris Dimitriadis (Ontologicon)
Karl Dubost (W3C)
Peter Fawcett (RealNetworks)
Kirill Gavrylyuk (Microsoft)
Dominique Haza�l-Massieux (W3C)
Lofton Henderson (CGM Open)
Ian Jacobs (W3C)
David Marston (Lotus Development Corp)
Sandra Martinez (NIST)
Patrick Curran (Sun Microsystems)
Lynne Rosenthal (NIST)
Mark Skall (NIST)
Andrew Thackrah (Open Group)
Olivier Th�reaux (W3C)

References

DOM-TS-PROC: DOM TS Process Document, D. Dimitriadis, Ed., 15 January 2002, available at http://www.w3.org/DOM/DOMTS-Process.
PROCESS: World Wide Web Consortium Process Document, I. Jacobs, Ed., 19 July 2001, available at http://www.w3.org/Consortium/Process-20010719/.
QAF-OPS: QA Framework: Operational Guidelines, K. Gavrylyuk, D. Dimitriadis, L. Henderson, L. Rosenthal, Eds., W3C Working Draft, May 2002, companion version to this document, available at [...].
QAF-SPEC: QA Framework: Specification Guidelines, L. Rosenthal, D. Dimitriadis, L. Henderson, K. Gavrylyuk, Eds., W3C Working Draft, May 2002, Working Draft companion version to this document, available at [...].
SVG-MAN: SVG Conformance Test Suite -- Test Builder's Manual, L. Henderson, 1 October 2001, available at http://www.w3.org/Graphics/SVG/Test/svgTest-manual.htm.
QAIG: Quality Assurance Interest Group of the W3C QA Activity, which may be found at http://www.w3.org/QA/IG/.
QAWG: Quality Assurance Working Group of the W3C QA Activity, which may be found at http://www.w3.org/QA/WG/.
W3C-TR: Location of all published W3C technical reports, see http://www.w3.org/TR/.

Change history

2003-09-05, New version.

Reformatting the document to be synchronized with http://www.w3.org/TR/2003/WD-qaframe-spec-20030912/

Using the new Working Group Note Style sheet

Using the new QA guidelines Style sheet

Changed the Status information to add the decision for publishing as a Note.

Reorganized the markup to use QA guidelines CSS.

Removed Old CP 1.3 Old CP 1.4 becomes New CP 1.3

Guideline 4 has moved to Guideline 3.

Moved Old CP 4.1 to New CP 3.1, Old CP 4.2 to New CP 3.2, Old CP 4.4 to New CP 3.3, removed Old CP 4.3, Moved Old CP 5.1 to New CP 3.4, Moved Old CP 5.2 to New CP 3.5

Moved Old GL 7 to New GL 4

Moved Old CP 7.1 to New CP 4.1

Moved Old CP 7.2 to New CP 4.2

Changed the anchor #CK-deprecated-class-support1 to #CK-deprecated-class-support. Added support for the old one.

Moved Old CP 7.3 to New CP 4.3

Moved Old CP 7.4 to New CP 4.4

Moved Old CP 7.5 to New CP 4.5

Created New CP 4.6

Moved Old GL 8 to New GL 5

Moved Old CP 8.1 to New CP 5.1

Moved Old CP 8.2 to New CP 5.2. Changed wording on the CP

Moved Old CP 8.3 to New CP 5.3

Moved Old CP 8.4 to New CP 5.4

Moved Old CP 8.5 to New CP 5.5

Moved Old GL 9 to New GL 6

Moved Old CP 9.1 to New CP 6.1

Removed Old CP 9.2

Moved Old CP 9.3 to New CP 6.2

Moved Old CP 9.4 to New CP 6.3

Moved Old CP 9.5 to New CP 6.4

Moved Old CP 9.5 to New CP 6.5. Changed the wording.

Moved Old CP 9.5 to New CP 6.6

Moved Old GL 13 to New GL 7

Moved Old CP 13.1, 13.2, 13.3, 13.3 to New CP 7.1, 7.2, 7.3, 7.4

Moved Old CP 10.2 to New GL 7.5

Moved Old GL 3 to New GL 8

Moved Old CP 3.1, 3.2, 3.3 to New CP 8.1, 8.2, 8.3

Moved Old CP 10.1 to New GL 8.4

Moved Old CP 11.1 to New GL 8.5

Moved Old GL 11 to New GL 9

Moved Old CP 11.2, 11.3, 11.4, 12.1, 12.2 to New CP 9.1, 9.2, 9.3, 9.4, 9.5

Moved Old GL 14 to New GL 10

Moved Old CP 14.1, 14.2 to New CP 10.1, 10.2

Added Table of Contents, Added wording for Specifications Guidelines in Action

2003-02-03, New version.

Reformatted the document with regard to the new version which is ready for Last Call. Cf: http://www.w3.org/TR/2003/WD-qaframe-spec-20030912/guidelines-chapter

Added new examples.

Added stylesheet of spec guidelines..

Added Techniques designed by Lynne Rosenthal (NIST) and Dominique Hazaël-Massieux (W3C)

2002-12-02, New version.

New Editing and addition of the contents of the old Specification Guidelines

2002-11-12, Holder of content.

Added Front and Back content for the Examples and Techniques

2002-11-08, skeleton.

Skeleton to start to edit the Examples and Techniques for QA Specification Guidelines.

2002-07-15, first public version, not published.

A version which has been organized to help and define which belongs to the example techniques.

The way it has been organized is slightly different from the QA Operational Guidelines Examples and Techniques which review only 3 Specs. This publication has taken examples in all specifications when the examples were available.

The editing has been made difficult by the verbosity of examples already given in QA Specification Guidelines

QA Framework: Specification Examples and Techniques

W3C Working Group Note 12 September 2003

Abstract

Status of this document

Table of contents

Introduction

Rationale

Specification guidelines in action

Guideline 1. Define Scope.

Checkpoint 1.1 Include a scope statement. [Priority 1]

Examples

Techniques

Checkpoint 1.2 Illustrate scope. [Priority 2]

Examples

Techniques

Checkpoint 1.3 Illustrate functional details. [Priority 2]

Examples

Techniques

Guideline 2. Identify what needs to conform and how.

Checkpoint 2.1 Identify all classes of product. [Priority 1]

Examples

Techniques

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

Examples

Techniques

Checkpoint 2.3 Identify the applicable specification categories. [Priority 3]

Examples

Techniques

Checkpoint 2.4 If there are several classes of products, define their relationships and interaction with other dimensions of variability. [Priority 2]

Examples

Techniques

Guideline 3. Address the use of profiles, modules and levels to divide the technology.

Checkpoint 3.1 Indicate whether or not the use of profiles is mandatory for conformance. [Priority 1]

Examples

Techniques

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

Examples

Techniques

Checkpoint 3.3 If profiles are chosen, address rules for profiles. [Priority 2]

Examples

Techniques

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

Examples

Techniques

Checkpoint 3.5 If profiles, modules or levels are used, define their relationships and interaction with other dimensions of variability. [Priority 2]

Examples

Techniques

Guideline 4. Identify the relation between deprecated features and conformance.

Checkpoint 4.1 Identify each deprecated feature. [Priority 1]

Examples

Techniques

Checkpoint 4.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]

Examples

Techniques

Checkpoint 4.3 If deprecated features exist, define their relationships and interaction with other dimensions of variability. [Priority 2]

Examples

Techniques

Checkpoint 4.4 Include an explanation for the deprecation. [Priority 3]

Examples

Techniques

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

Examples

Techniques

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

Examples

Techniques

Guideline 5. Define discretionary items.

Checkpoint 5.1 State the circumstances for when discretionary items are allowed [Priority 1]

Examples

Techniques

Checkpoint 5.2 For implementation dependent values or features, address the allowable differences between implementations. [Priority 1]

Examples

Techniques

Checkpoint 5.3 Indicate any constraints on the number of choices/options that can be implemented for discretionary choices [Priority 2]

Examples

Techniques

Checkpoint 5.4 Promote consistent handling of discretionary choices. [Priority 2]

Examples

Techniques

Checkpoint 5.5 If discretionary items are used, define their relationships and interaction with other dimensions of variability. [Priority 2]

Checkpoint 7.5 Make normative reference to specifications on which the current specification depends [Priority 1]