This document is not a published and official version, it has been just released publically to help for the review with other editors.
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 for writing specifications inside W3C. It complements QA Framework: Specification Guidelines [QAF-SPEC], by specifying or illustrating how to meet the checkpoints for writing a better specification 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.
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.
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.
Here the table of contents.
[Overview and summary information, see examples in the review matrix, for what to put here for your specific Guideline type (Ops, Spec, Test).]
[@@Ed: We must define somewhere what does that mean to generate a table of contents entry because we are using it very often. Does that mean: ...]
[@@Ed: Some concepts need to be clarified like]
Guideline 1. Define user scenarios.
[...per-Guideline summary/overview verbiage goes here...]
1.1 Define the scope of the specification. [Priority 1]
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.
1.2 Include Use Cases. [Priority 2]
1.3 Include examples. [Priority 1]
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.
1.4 Include an interpretation section. [Priority 2]
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.
Guideline 2. Identify what needs to conform and how.
[...per-Guideline summary/overview verbiage goes here...]
2.1 Identify all classes of product. [Priority 1]
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.
2.2 For each class of product, define the conformance requirements. [Priority 1]
Ruby. See checkpoint 2.1 @@mmm not sure it's acceptable@@
XHML Modularization. See checkpoint 2.1 .
2.3 Indicate minimal support requirements. [Priority 3]
SMIL. When a class of product has been defined, you may define a minimal set of elements and/or attributes as it has been done in the SMIL Specification which defines what is the set to be implemented in a SMIL Host language. It means if you decide to integrate SMIL in another technology like SVG or XHTML, you'll have to give at least this set.
Ruby. The conformance section of Ruby defines, for example, for a document type is a conforming simple ruby markup document type if it integrates conforming simple ruby markup by adding the ruby element to the appropriate elements (such as inline elements) and by defining the necessary elements and attributes.
. It could have been a little been more explicit and gives a detailed table of this element and attributes.
2.4 Identify which of the categories of object are specified in the document as a whole. [Priority 3]
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.
Guideline 3. Address the use of profiles to divide the specification.
[...per-Guideline summary/overview verbiage goes here...]
3.1 Choose whether or not to have profiles. [Priority 1]
SMIL 2.0. In the chapter on Modules, SMIL 2.0 defines, as a informative part, the notion of Profiles and explains The main purpose of language profile conformance is to enhance interoperability.
.
3.2 If profiles are chosen, ensure that a table of contents entry is generated. [Priority 1]
SMIL 2.0. The table of contents of SMIL 2.0 explicit gives an entry for profiles : 13. SMIL 2.0 Language Profile
.
3.3 If profiles are chosen, indicate whether or not their use is mandatory for conformance. [Priority 1]
3.4 If profiles are chosen, define any minimal requirements. [Priority 2]
3.5 If profiles are chosen, define their relationships and interaction with other dimensions of variability. [Priority 2]
Guideline 4. Address the use of modules to divide the specification.
[...per-Guideline summary/overview verbiage goes here...]
4.1 Choose whether or not to have modules. [Priority 1]
CSS TV Profile 1.0.
SMIL 2.0.
XHTML Modularization
4.2 If modules are chosen, ensure that a table of contents entry is generated. [Priority 1]
DOM Level 2. In the section conformance of DOM Level 2 Core, the notion of modules is explicited but there's no apparent table of contents entry for it. The specification should contain this entry.
SMIL 2.0.
XHTML Modularization
4.3 If modules are chosen, indicate any mandatory conditions or constraints on their usage. [Priority 1]
CSS TV Profile 1.0.
SMIL 2.0.
XHTML Modularization
4.4 If modules are chosen, define their relationships and interaction with other dimensions of variability. [Priority 2]
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.
Guideline 5. Specify conformance policy.
[...per-Guideline summary/overview verbiage goes here...]
5.1 Make it clear where there are universal requirements for minimum functionality. [Priority 1]
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.
5.2 Make it clear when conformance requirements are strict. [Priority 1]
[@@Ed: never the words "strict conformance" is used in the TR space. interesting.]
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.
5.3 Make it clear where requirements stop and product-specific extra features begin. [Priority 1]
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.
5.4 The conformance clause should contain or refer to the conformance policy. [Priority 1]
XHTML 1.1. The specification is built on top of Modularization of XHTML, when it comes to define the user agent conformance, they refer to the conformance policy of the XHTML modularization: A conforming user agent must meet all user agent conformance requirements defined in [XHTMLMOD].
.
5.5 If special conformance terms are used, include a definition in the specification. [Priority 1]
Guideline 6. Clarify the relation between deprecated features and conformance.
[...per-Guideline summary/overview verbiage goes here...]
6.1 Identify and clearly indicate each deprecated feature. [Priority 1]
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.
6.2 For each class of product, specify the level of support required for each deprecated feature and the conformance consequences of the deprecation. [Priority 1]
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.
6.3 Include an explanation for the deprecation. [Priority 3]
HTML 4.01. The specification defines the word deprecated with regards to HTML 4.01.
[@@Ed - SMIL 2.0 doesn't define deprecated, DOM Level 2 either, I have hard time to find specification which defines it... :( very bad thing.]
6.4 Include examples to illustrate how to avoid using deprecated features. [Priority 3]
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
.
6.5 Generate a table of contents entry. [Priority 2]
MathML 2.0. The specification defines the deprecated features of MathML 1.0 but doesn't have a table of contents entry. So the definition of deprecated features is not visible.
Guideline 7. Address the use of levels to divide the specification.
[...per-Guideline summary/overview verbiage goes here...]
7.1 Choose whether or not to have levels. [Priority 1]
[@@Ed: Do we have examples of specifications where the next level was already planned at the writing of the preceding level.]
7.2 If levels are chosen, ensure that a table of contents entry is generated. [Priority 1]
[@@Ed: the table of contents entry which explains the notion of level or a table of contents entry by level?]
7.3 If levels are chosen, define their relationships and interaction with other dimensions of variability. [Priority 2]
[@@Ed: where ? where ? where ?]
Guideline 8. Define discretionary behaviors.
[...per-Guideline summary/overview verbiage goes here...]
8.1 Explicitly state the cases and conditions where discretion is allowed and/or expected. [Priority 2]
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.
8.2 Indicate implementation dependencies and where applicable address, allowable differences between implementations. [Priority 1]
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.
.
8.3 Describe alternative approaches and the conditions under which an implementation is considered to be conforming. [Priority 1]
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.
8.4 Include a statement regarding consistent handling of a discretionary item within an implementation. [Priority 2]
8.5 Generate a table of contents entry. [Priority 2]
[@@Ed: does it make sense to generate a table of contents entry when it addresses a single attributes in the spec. And if there are a lot of discretionnary behaviours, we will end up with a lot of table of contents entry, just a question.]
Guideline 9. Allow extensions or NOT!
[...per-Guideline summary/overview verbiage goes here...]
9.1 If extensions are disallowed, explicitly state it. [Priority 3]
9.2 If extensions are allowed, explicitly state it. [Priority 1]
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.
9.3 If extensions are allowed, make it clear that the extensions do not negate support for required functionality. [Priority 1]
9.4 If extensions are allowed, use a standard mechanism to define the extension. [Priority 3]
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.
9.5 If extensions are allowed, register or publish them. [Priority 3]
9.6 If extensions are allowed, require that implementations include a way to operate without the extension. [Priority 3]
9.7 Generate a table of contents entry. [Priority 2]
Guideline 10. Provide a conformance clause.
[...per-Guideline summary/overview verbiage goes here...]
10.1 Include a conformance clause. [Priority 1]
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.
10.2 Create a separate conformance section. [Priority 2]
[@@Ed: Some specs has sort of conformance clause but not explicit. So can we show to not do like that ???]
An example of that is DOM Level 2 Core
10.3 Generate a conformance clause entry in the table of contents. [Priority 2]
Guideline 11. Specify how to make conformance claims.
[...per-Guideline summary/overview verbiage goes here...]
11.1 Identify and define all conformance levels or designations. [Priority 1]
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.
11.2 Provide specific wording of the claim. [Priority 3]
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.
11.3 Provide a conformance disclaimer. [Priority 3]
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.
11.4 Impose no restrictions about who can make a claim or where claims can be published. [Priority 1]
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).
11.5 Generate a table of contents entry. [Priority 2]
UAAG 1.0. The conformance section of UAAG 1.0 gives a specific table of contents entry for well formed conformance claims and for validity of a claim.
Guideline 12. Publish an Implementation Conformance Statement proforma.
[...per-Guideline summary/overview verbiage goes here...]
12.1 Include an Implementation Conformance Statement proforma as part of the specification. [Priority 3]
12.2 Require the ICS be completed as part of the conformance claim. [Priority 3]
Guideline 13. Support general document conformance conventions.
[...per-Guideline summary/overview verbiage goes here...]
13.1 Use conformance key words. [Priority 1]
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].
13.2 Distinguish normative and informative text. [Priority 2]
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
.
13.3 Follow Web Accessibility Initiative and Internationalization Guidelines. [Priority 1]
[@@Ed: I agree but will be difficult to illustrate]. The pubrules are for examples allready have a set of things to respect with regards to the accessibility. We are not talking about the technology but the spec itself. For example PubRules 1.6.2 # The document must conform to the Web Content Accessibility Guidelines 1.0, Level A. Use the WCAG 1.0 Checklist (5 May 1999 version).
But there's no mention for I18N like Charmod for example (it's not yet a spec).
13.4 Use the same words to express the same ideas. [Priority 1]
[@@Ed: Once again difficult to illustrate, it maybe easier to find an example of what you should not do]
Guideline 14. Use granular grammars to author the specification.
[...per-Guideline summary/overview verbiage goes here...]
14.1 Use W3C endorsed grammar where applicable. [Priority 1]
14.2 Specify intended behavior in the specification using markup. [Priority 1]
14.3 Supply prose description of intended behavior together with each test assertion. [Priority 1]
Guideline 15. Include test assertions.
[...per-Guideline summary/overview verbiage goes here...]
15.1 Supply test assertions in the markup of the specification, if applicable using a set of predefined tags used in the specification markup language. [Priority 1]
15.2 Tag test assertions according to the above. [Priority 1]
[Optional: opinions, observations, assessment, judgements, etc, about the subject of your review, about the review process, the Guidelines document, etc.]
The following QA Working Group and Interest Group participants have contributed significantly to the content of this document: