Copyright © 2003 W3C ® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply.
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.
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.
@@to write text here@@
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:
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].
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.
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
(Under Construction)
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.
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.
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.
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.
State what must conform.
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.
State how the class of product would conform.
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.
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.
(Under Construction)
(Under Construction)
(Under Construction)
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.
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)
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
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.
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.
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.
(Under Construction)
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.
(Under Construction)
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.
Include a normative section that lists the deprecated features
Tag each deprecated feature - this allows it to be extracted into another document, indexed, etc.
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.
Include a normative table that lists each deprecated feature and whether or not it must be implemented by the class of product.
(Under Construction)
(Under Construction)
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.
Provide alternative ways to implement the feature
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
.
(Under Construction)
(Under Construction)
(Under Construction)
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.
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.
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.
.
(Under Construction)
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.
- An HTTP "charset" parameter in a "Content-Type" field.
- A META declaration with "http-equiv" set to "Content-Type" and a value set for "charset".
- The charset attribute set on an element that designates an external resource.
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.
@@more a technique than an example, or if you have an example tell me.@@
(Under Construction)
(Under Construction)
(Under Construction)
(Under Construction)
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.
(Under Construction)
(Under Construction)
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.
Signal that an extension will follow by using a special character(s) or namespace
(Under Construction)
Provide web space that contains a list of extensions, each with a general description and a functional description (their syntax and semantics)
(Under Construction)
(Under Construction)
(Under Construction)
(Under Construction)
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].
(Under Construction)
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
.
(Under Construction)
(Under Construction)
(Under Construction)
(Under Construction)
Include a Table of Contents which would include the conformance section and all conformance-related sections
Include an index for all conformance-related topics
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.
Include a section, "References (normative)" that lists specification on which the current specification depends.
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.
(Under Construction)
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:
- a version of UAAG 1.0,
- a set of requirements in that document, and
- a list of specifications implemented to satisfy some of those requirements.
Put definition of conformance terms in the glossary or terminology section of the document
(Under Construction)
(Under Construction)
Example in DOM Level 2 Core
(Under Construction)
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.
(Under Construction)
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.
(Under Construction)
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.
(Under Construction)
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).
(Under Construction)
UAAG 1.0 explains how User Agent can claim conformance and gives a sample of this Conformance Statement.
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.
(Under Construction)
(Under Construction)
(Under Construction)
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.
(Under Construction)
(Under Construction)
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.
The following QA Working Group and Interest Group participants have contributed significantly to the content of this document:
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
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)
New Editing and addition of the contents of the old Specification Guidelines
Added Front and Back content for the Examples and Techniques
Skeleton to start to edit the Examples and Techniques for QA Specification Guidelines.
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