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.
Table of contents
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 has been drastically modified and this version will be completely different from the previous version.
Examples and Techniques
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
Examples
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
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.
Techniques
Collecting a series of usage scenarios demonstrates the relevance and use of the specification.
Provide a description of a context of use of the specification
- describe the typical operations that the users of the specification may perform and the results that are obtained
- describe the interrelationship of this technology with other W3C technologies
Include a list of use cases in an appendix
Link to a separate requirements document that includes describesthe relationship of use cases to requirement.
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
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
Examples
Techniques
Examples
Techniques
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
Examples
Techniques
Examples
Techniques
(Under Construction)
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)
Examples
Techniques
Examples
- CSS TV Profile 1.0. The profile has been defined to work with CSS 2 and the Modules of CSS 3. The conformance section of the CSS TV profile defines the interaction when it occurs. The specification gives the list of elements and attributes and their behaviour in the profile.
Techniques
(Under Construction)
Examples
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 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)
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)
Examples
@@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.
Techniques
(Under Construction)
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
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
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
Techniques
(Under Construction)
Examples
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 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)
Examples
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.
Examples
Techniques
(Under Construction)
Examples
Techniques
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.
Examples
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.
Techniques
(Under Construction)
Examples
(Under Construction)
Techniques
(Under Construction)
Examples
Techniques
Examples
(Under Construction)
Techniques
Examples
(Under Construction)
Techniques
(Under Construction)
Examples
Techniques
Examples
Techniques
(Under Construction)
Examples
Techniques
Examples
Techniques
(Under Construction)
Examples
Techniques
(Under Construction)
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)
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)
Examples
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.
Examples
(Under Construction)
Techniques
(Under Construction)
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)
Examples
Techniques
(Under Construction)
Examples
(Under Construction)
Techniques
(Under Construction)
Examples
(Under Construction)
Techniques
Examples
(Under Construction)
Techniques
Examples
(Under Construction)
Techniques
(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:
- Daniel Dardailler (W3C)
- Dimitris Dimitriadis (Ontologicon)
- Karl DuBost (W3C)
- Peter Fawcett (RealNetworks)
- Kirill Gavrylyuk (Microsoft)
- Dominique Hazael-Massieux (W3C)
- Lofton Henderson (CGM Open)
- Ian Jacobs (W3C)
- David Marston (Lotus Development Corp)
- Sandra Martinez (NIST)
- Jack Morrison (Sun Microsystems)
- Lynne Rosenthal (NIST)
- Mark Skall (NIST)
- Andrew Thackrah (Open Group)
- Olivier Thereaux (W3C)
- 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/.
- 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/QA/WG/2003/01/qaframe-spec/
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