Copyright © 2002 W3C ® (MIT, INRIA, 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 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. This version should be published soon. It's still a Working Draft but your comments or examples are welcome.
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 has been drastically modified and this version will be completely different from the previous version.
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.
(Under Construction)
UAAG 1.0 specification defines 3 scenarios (Keyboard accessibility, Access to all content, Communication with assistive technologies) which show how some of the requirements "User Agent Accessibility Guidelines 1.0" benefit users with disabilities
. These 3 scenarios help developpers to understand the context of the specifications.
Web Services Description Usage Scenarios [WS-DES-USECASES] describes the use cases of the web services description language. The use cases are meant to capture what is important for a web service to describe itself. There may be several other important aspects of a web service but irrelevant to its operational and interaction descriptions
.
XMLP Reqs [XMLP-REQS] defines a list of usage scenarios which are intended to provide representative examples of situations where XMLP might be applicable. The purpose of usage scenarios is to help ensure that XMLP is capable of dealing with applications and services actually seen in the Web. Hence, usage scenario specifications should be at a coarse-grain level of an end user's desired XML document/message interchange, rather than at a detailed, implementation or transport specific level. Usage scenarios often make assumptions about the specific environments in which the use cases are described that the requirements cannot.
The Basic usage scenarios have been developed in the Primer part of the SOAP Version 1.2 Specification. The specification developed the scenarios based on a travel reservation application and covers all the cases of the transmission of a message with this protocol.
(Under Construction)
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.
(Under Construction)
SOAP. There's often a necessity to give a introductory document to a technology. SOAP has realeased a Primer with the version 1.2 of this technology. The Primer is a separate document in this case, with markup and graphical schema to give a comprehensive overview of XML Protocol. The document precises that SOAP Version 1.2 Part 0: Primer is a non-normative document ...
RDF. One of the biggest problem of the first release of the RDF specification was the lack of understanding in the community. A primer is often another way to present the fundamental concepts of a technology and to help people (users and developpers) to read the specification with a better background. The RDF primer presents the technology as large but also some applications where the technology is used.
(Under Construction)
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.
XHML 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.
(Under Construction)
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.
(Under Construction)
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)
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)
XHTML 1.0. The notion of strictly conforming documents and strictly conforming user agents is defined in XHTML 1.0 with the following wording This version of XHTML provides a definition of strictly conforming XHTML documents, which are restricted to tags and attributes from the XHTML namespace.
The minimum level of conformance is Basic. A minimally conformant implementation must process as specified all the formatting objects and properties defined for the Basic level of the implementation's target medium.
(Under Construction)
XHTML 1.0. If XHTML 1.0 is used in a document with other namespaces is not anymore a strictly conforming document. They do not define other kind of conformance and the specification says Future work by W3C will address ways to specify conformance for documents involving multiple namespaces.
(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.
(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.
(Under Construction)
(Under Construction)
(Under Construction)
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.
(Under Construction)
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)
@@better examples should be found@@
DOM Level 3 Core defines its relationship with DOM Level 2 Core as backward compatible with the DOM Level 2 Core [DOM Level 2 Core] module, i.e. a DOM Level 3 Core implementation who returns true for "Core" with the version number "3.0" must also return true for this feature when the version number is "2.0", "" or, null.
(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.
(Under Construction)
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.
(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.
(Under Construction)
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)
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.
(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.
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.
(Under Construction)
@@more a technique than an example, or if you have an example tell me.@@
(Under Construction)
(Under Construction)
(Under Construction)
XSL 2.0. This specification provides an extension mechanism XSLT allows two kinds of extension, extension instructions and extension functions.
. A whole chapter is dedicated to this extensibility.
XHTML Modularization. The extension mechanism is one of the fundamental base of the design of XHTML Modularization: These modules [abstract modules] may be combined with each other and with other modules to create XHTML subset and extension document types that qualify as members of the XHTML-family of document types.
(Under Construction)
(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.
(Under Construction)
(Under Construction)
(Under Construction)
(Under Construction)
(Under Construction)
XHTML 1.0. The Specification of XHTML 1.0 defines the conformance clause for documents and user agents.
Ruby. The specification also has a very detailed conformance clause,even if the specification is not a big document.
(Under Construction)
Example in DOM Level 2 Core
(Under Construction)
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.
(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.
(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)
(Under Construction)
(Under Construction)
(Under Construction)
(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:
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