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.
Table of contents
Here the table of contents.
Front matter
[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: ...]
- Having an entry in the General TOC. Like XHTML Mod toc
- Having an entry in the Full TOC. like XHTML Mod Full Toc
- Sometimes like for XHTML 1.0, the TOC does not contain all the entries :( bad. See 3.1.1 of XHTML 1.0 that you don't find in the toc of XHTML 1.0
[@@Ed: Some concepts need to be clarified like]
- What's the notion of modules
- What's the notion of level
- Redefine the conditionnal nature of Checkpoint for exemple if you don't have module Checkpoint 4.1 P1 you don't have to satisfy checkpoint 4.2, 4.3, etc which are also P1.
- You don't necessary know that you will have a future to your specification so the notion of level is not clear.
Guidelines and Checkpoints
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]
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]
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]
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]
- 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.
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]
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]
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]
6.5 Generate a table of contents entry. [Priority 2]
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]
7.2 If levels are chosen, ensure that a table of
contents entry is generated. [Priority 1]
7.3 If levels are chosen, define their
relationships and interaction with other dimensions of variability. [Priority 2]
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]
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]
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]
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.
- SVG 1.0. Exactly in the same way, SVG has a very detailed conformance clause.
10.2 Create a separate conformance section. [Priority 2]
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]
11.2 Provide specific wording of the claim. [Priority 3]
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]
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]
13.3 Follow Web
Accessibility Initiative and Internationalization Guidelines. [Priority 1]
13.4 Use the same words to express the same
ideas. [Priority 1]
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]
Back matter
[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:
- 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)
-
SPEC
-
QA Framework: Specification
Guidelines
, D. Dimitriadis, L. Henderson, L. Rosenthal,
Eds., W3C Working Draft, May 2002, Working Draft companion version to
this document, available at [...].
-
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/.