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.

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

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.

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

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.

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.

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

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".

Techniques

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.

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)

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.

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 conformantif 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

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

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.

Examples

Techniques

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

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.

Examples

Techniques

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 cascadeThe 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.

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 cascadeThe 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..

Examples

Techniques

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

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 conformantif 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

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

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

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).

Examples

Techniques

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.

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