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:

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:

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:

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:

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 guidelines are of two general types:

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

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: