1. Introduction

1.1. Scope and Goals

The scope of this document is a set of requirements for W3C Technical Reports (TRs) that if satisfied, will enhance the clarity, implementability, and testability of TRs. It describes what goes into a TR with respect to conformance and conformance topics, dealing with how a TR establishes, defines, and presents its conformance policy. This document addresses the most basic and critical topics with respect to conformance and testabily; more advanced topics will be addressed in future versions. This document includes:

• This introduction, which provides for context understanding the requirements in section 3, as well as use scenarios or examples of how this document could be used.
• Section 2 explains the main concepts used throughout the guidelines.
• Section 3 contains ten guidelines. Each guideline consists of one or more verifiable "checkpoints". Each checkpoint includes the conformance requirements that a specification would need to meet in order to satisfy the checkpoint. There are two general types of guidelines, those that deal with the document features and conventions of the specification and those that deal with establishing and defining conformance policy.
• Section 4 explains how to make conformance claims that W3C TRs satisfy the requirements of section 2. It defines conformance for this document.
• An appendix lists all the guidelines and checkpoints into an Implementation Conformance Statement (ICS) pro forma for this specification, which is required to be completed as part of the conformance claim to this document.

A separate document, entitled "Specification Examples and Techniques 1.0" (the "ExTech document" from here on) provides suggestions and examples of how each checkpoint might be satisfied. The techniques in the ExTech document are informative examples only, other strategies may be used or required to satisfy the checkpoints. The ExTech document is expected to be updated more frequently than the current guidelines. Developers, W3C Working Groups, users, and others are encouraged to contribute techniques and examples.

1.2. Class of Product and Audience

The specification category for this specification is "guideline". The class of product or target of this specification is "specification", in particular W3C Technical Reports. Within this Specification Guidelines document, the term "specifications" is specifically limited to W3C Technical Reports, even though these guidelines could be applied to other documents.

The primary target audience of this document is specification authors, however, it is applicable to a broader audience including:

• those who review specifications during their development,
• implementers of specifications,
• those who use specifications to build test materials.

These guidelines are designed so that the WGs can apply them in a common-sense and workable manner.

1.3. Motivation and expected benefits

Good specifications lead to better implementations and foster the development of conformance test suites and tools. Conforming implementations lead to interoperability.

The quality of the specification has direct impact on the quality of implementations. Quality encompasses utility which refers to the usefulness of the specification to the intended users and objectivity which focuses on the whether the specification is presented in an accurate, clear, complete, and unbiased manner.

Providing requirements and definitions about conformance topics, as well as guidance in the structure and anatomy of specifications, will foster a mutual understanding among those developing specifications, implementations, and conformance test materials. Specifically, well-structured specifications with clear and comprehensive conformance requirements:

• promote a common understanding of conformance and what is required to claim conformance to a specification,
• facilitate consistent application of conformance within a specificationand across related specifications,
• promote better interoperability and open interchange,
• promote uniformity in the development of conformance test suites,
• enhance test assertion identification and test traceability,
• promote automated test generation directly from the specifications.

1.4. Relationship to other specifications

This document is part of a family of QA Framework documents designed to help the WGs improve all aspects of their quality practices. The QA Framework documents are:

• QA Framework: Introduction [QAF-INTRO].
• QA Framework: Operational Guidelines [QAF-OPS].
• QA Framework: Specification Guidelines (this document).
• QA Framework: Test Guidelines [QAF-TEST].

Although the QA Framework documents are interrelated and complement each other, they are independently implementable. For example, the anatomy of a specification is related to the type of test materials that will be built, hence there is an interrelationship between this document and the Test Guidelines. The reader is strongly encouraged to be familiar with the other documents in the family.

The Framework as a whole is intended for all Working Groups, as well as developers of conformance materials for W3C specifications. Not only are the Working Groups the consumers of these guidelines, they are also key contributors. The guidelines capture the experiences, good practices, activities, and lessons learned of the Working Groups and present them in a comprehensive, cohesive set of documents for all to use and benefit from. The objective is to reuse what works rather than reinvent and to foster consistency across the various Working Group quality activities and deliverables.

This document does not preclude the need to apply the W3C Manual of Style [STYLE-MAN] and to conform to the Publication Rules [PUBRULES] (Member-only). It is intended to complement those resources.

1.5. Understanding and using this document

This document employs the WAI (Web Accessibility Initiative) model for representing guidelines or general principles for the development of conformance materials. See, for example, Web Content Accessibility Guidelines 1.0 [WCAG10]. Each guideline includes:

• the guideline number,
• the statement of the guideline,
• the rationale behind the guideline,
• a collection of one or more checkpoints.

The guidelines are of two general types:

• those that deal solely with the document features and conventions of the specification — (GL 1, GL 7, GL9-10),
• those that, in addition to documentation aspects, deal with how specifications should establish and define the conformance policy for the specification's technology, including ways in which the technology may be subdivided for conformance purposes —(GL 2-6 and GL 8).

The checkpoints in each guideline define specification characteristics and requirements needed to fulfill the purpose of the guideline. Each checkpoint definition includes:

• the checkpoint number,
• the statement of the checkpoint (its "title"),
• the priority of the checkpoint,
• a statement of the conformance requirements of the checkpoint, i.e., how to fulfill the checkpoint,
• optional informative notes, clarifying examples, and cross references to related guidelines or checkpoints,
• a link to the corresponding section in Specification Examples & Techniques.

Each checkpoint is intended to be specific enough so that someone can implement the checkpoint as well as verify that the checkpoint has been satisfied. A checkpoint will contain at least one, and may contain multiple individual requirements, that use RFC2119 normative keywords. See the "Conformance" chapter for further discussion of requirements and test assertions.

Two separate appendices to this document [SPEC-CHECKLIST] and [SPEC-ICS] present all checkpoints in a tabular form sorted in their original order and sorted by their priorities, for convenient reference. The latter is an Implementation Conformance Statement (ICS) pro forma for this specification. (See GL9.).

1.6. Usage of terminology in this document

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY ", and "OPTIONAL" will be used as defined in RFC 2119 [RFC2119]. When used with the normative RFC2119 meanings, they will be all uppercase. Occurrences of these words in lowercase comprise normal prose usage, with no normative implications.

Unusual terms in these framework documents are defined when first used. When used in this specification, terms have the meaning assigned in the "Definitions" chapter and the QA Glossary [QA-GLOSSARY]. Terms in Definitions may supplement or build on the definitions in the generic QA Glossary, further refining the definition in the context of the Specifications guidelines. Terms herein that also appear in the QA Glossary include a link to the QA definition.They will not contradict the generic definitions.

1.7. Checkpoint priorities

Some checkpoints are more critical than others for producing a high quality, testable standard that is a sound basis for successfully interoperable products. Therefore each checkpoint is assigned a priority level based on the checkpoint's impact on the quality of the specifications produced by the Working Groups.

[Priority 1]

Critical/Essential. These checkpoints are considered to be basic requirements for ensuring an acceptable level of quality and testability in the specification.

[Priority 2]

Important/desirable. Satisfying these checkpoints, in addition to the priority 1 checkpoints, should significantly improve the clarity, quality, and testability of the standard, as well as its suitability as a basis for building quality test materials.

[Priority 3]

Useful/beneficial. Satisfying these checkpoints, on top of all the others, will further improve the quality, usability, and testability of the specification.

1.8. Use cases

The Specification Guidelines are intended to be used in the following typical cases:

• A Working Group is developing a new specification or a new edition of a specification. The WG gets familiar with the principles in the Specification Guidelines as early as possible, since it can influence what goes into the specification as well as the organization, structure, and presentation of content in the specification.
• A Working Group is concerned by interoperability issues discovered during the implementations phase (e.g. during the Candidate Recommendation), and tries to address them by making the conformance requirements more constraining. It uses the Specification Guidelines to identify the common interoperability issues explained in the document.
• A Working Group develops a specification that it wants to move to Candidate Recommendation in the near future and knows that it will develop a Test Suite during this phase; to ensure that the building of the Test Suite will be as efficient and accurate as possible, it uses the Specification Guidelines to have a clearer idea on how to make the specification testable.
• A Working Group has committed in its charter to the Specification Guidelines for its specifications (as required for A conformance to the Operational Guidelines, for instance), and has picked the AA conformance level; it uses the Specification Guidelines to assess the conformance of its specifications at different stages of the specification life.
• A Working Group asks others to review their specification. The Working Group indicates its claim of conformance to the Specification Guidelines, i.e., the degree of conformance met. The reviewers use the Specification Guidelines as part of their evaluation criteria and ensure that the appropriate checkpoints in the Specification Guidelines are satisfied.