QA Specification Guidelines - Implementation Report

Introduction

This document serves as an implementation report of April 2005 version of SpecGL applied to a number of W3C specifications. For each specification, a separate table listing all SpecGL guidelines and whether the specification implements those is given.

Specification implementation report

Spec GL

Guidelines	YES	NO	N/A	Comments
2.1 Specifying Conformance
Requirement 01: Include a conformance clause.	yes
Good Practice 01: Define the specification's conformance model in the conformance clause.	yes
Good Practice 02: Specify in the conformance clause how to distinguish normative from informative content.	yes
Good Practice 03: Provide the wording for conformance claims.	yes
Good Practice 04: Provide an Implementation Conformance Statement Pro Forma.	yes
Good Practice 05: Require an Implementation Conformance Statement as part of valid conformance claims.	yes
2.2 Setting up ground rules
Requirement 02: Define the scope.	yes
Good Practice 06: Provide examples, use cases, and graphics.	Yes			SpecGL uses many examples, and the 3 embedded stories serve as use cases; it also uses 2 figures for illustration of some of the most complex concepts.
Good Practice 07: Write sample code or tests.	Yes			SpecGL techniques are the equivalent of sample code
Requirement 03: Identify who or what will implement the specification.	yes
Requirement 04: Make a list of normative references.	yes
Good Practice 08: When imposing requirements by normative references, address conformance dependencies.			N/A	SpecGL doesn't impose requirements by normative references, since the only normative reference is RFC 2119 used to define conformance vocabulary.
2.3 Defining and using terminology
Requirement 05: Define the terms used in the normative parts of the specification.	yes
Requirement 06: Create conformance labels for each part of the conformance model.	yes
Good Practice 09: Define the unfamiliar terms in-line, and consolidate the definitions in a glossary section.	Yes			See for instance how specification is defined in-line and in the glossary
Good Practice 10: Use terms already defined without changing their definition.	yes			SpecGL re-uses the ISO definition of specification, the RFC Keywords
Requirement 07: Use a consistent style for conformance requirements and explain how to distinguish them.	Yes
Requirement 08: Indicate which conformance requirements are mandatory, which are recommended and which are optional.	yes
Good Practice 11: Use formal languages when possible.			N/A	SpecGL doesn't define machine-processable content, so this doesn't apply
Good Practice 12: Write Test Assertions.		No		SpecGL doesn't define Test Assertions.
2.4 Managing Variability
Good Practice 13: Create subdivisions of the technology when warranted.			N/A	SpecGL goal of use simplicity and focus on a consistent set of checkpoints does not need subdivisions.
Requirement 09: If the technology is subdivided, then indicate which subdivisions are mandatory for conformance.			N/A	see above
Requirement 10: If the technology is subdivided, then address subdivision constraints.			N/A	See above
Good Practice 14: If the technology is profiled, define rules for creating new profiles.			N/A	See above
Good Practice 15:Use optional features as warranted.				@@@
Good Practice 16: Clearly identify optional features.	Yes			In addition to Requirements, the document contains Good Practices. Good Practices are optional and considered recommendations.
Good Practice 17: Indicate any limitations or constraints on optional features.	Yes			It has optional features, but the optional features do not affect conformance.
Requirement 11: Address Extensibility.	Yes
Good Practice 18: If extensibility is allowed, define an extension mechanism.	Yes			This specification is extensible. That is, adding conformance related information and structure to the document in ways beyond what is presented as Requirements in this specification, is allowed and encouraged. Extensions to this specification must not contradict nor negate the requirements in this specification.
Good Practice 19: Warn extension creators to create extensions that do not interfere with conformance.	Yes			Extensions to this specification must not contradict nor negate the requirements in this specification.
Good Practice 20: Define error-handling for unknown extensions.			N/A	SpecGL doesn't have a class of product that can be affected by errors conditions
Requirement 12: Identify deprecated features.			N/A	First version of SpecGL
Requirement 13: Define how each each class of product handles each deprecated feature.			N/A	see above
Good Practice 21: Explain how to avoid using a deprecated feature.			N/A	see above
Good Practice 22: Identify obsolete features.			N/A	First version of SpecGL
Good Practice 23: Define an error handling mechanism.			N/A	SpecGL doesn't have a class of product affected by error conditions

Ruby

Guidelines	YES	NO	N/A	Comments
2.1 Specifying Conformance
Requirement 01: Include a conformance clause.	Yes
Good Practice 01: Define the specification's conformance model in the conformance clause.	Yes
Good Practice 02: Specify in the conformance clause how to distinguish normative from informative content.		No
Good Practice 03: Provide the wording for conformance claims.		No
Good Practice 04: Provide an Implementation Conformance Statement Pro Forma.		No
Good Practice 05: Require an Implementation Conformance Statement as part of valid conformance claims.		No
2.2 Setting up ground rules
Requirement 02: Define the scope.	Yes
Good Practice 06: Provide examples, use cases, and graphics.	Yes
Good Practice 07: Write sample code or tests.	Yes
Requirement 03: Identify who or what will implement the specification.	Yes
Requirement 04: Make a list of normative references.	Yes
Good Practice 08: When imposing requirements by normative references, address conformance dependencies.				Difficult
2.3 Defining and using terminology
Requirement 05: Define the terms used in the normative parts of the specification.	Yes
Requirement 06: Create conformance labels for each part of the conformance model.	Yes
Good Practice 09: Define the unfamiliar terms in-line, and consolidate the definitions in a glossary section.	Yes
Good Practice 10: Use terms already defined without changing their definition.				Difficult
Requirement 07: Use a consistent style for conformance requirements and explain how to distinguish them.		No
Requirement 08: Indicate which conformance requirements are mandatory, which are recommended and which are optional.	Yes
Good Practice 11: Use formal languages when possible.		No
Good Practice 12: Write Test Assertions.		No
2.4 Managing Variability
Good Practice 13: Create subdivisions of the technology when warranted.	Yes
Requirement 09: If the technology is subdivided, then indicate which subdivisions are mandatory for conformance.	Yes
Requirement 10: If the technology is subdivided, then address subdivision constraints.	Yes
Good Practice 14: If the technology is profiled, define rules for creating new profiles.			N/A
Good Practice 15:Use optional features as warranted.	Yes
Good Practice 16: Clearly identify optional features.	Yes
Good Practice 17: Indicate any limitations or constraints on optional features.	Yes
Requirement 11: Address Extensibility.		No
Good Practice 18: If extensibility is allowed, define an extension mechanism.		No
Good Practice 19: Warn extension creators to create extensions that do not interfere with conformance.		No
Good Practice 20: Define error-handling for unknown extensions.		No
Requirement 12: Identify deprecated features.			N/A
Requirement 13: Define how each each class of product handles each deprecated feature.			N/A
Good Practice 21: Explain how to avoid using a deprecated feature.			N/A
Good Practice 22: Identify obsolete features.			N/A
Good Practice 23: Define an error handling mechanism.	Yes

CSS 2.1

Guidelines	YES	NO	N/A	Comments
2.1 Specifying Conformance
Requirement 01: Include a conformance clause.	Yes
Good Practice 01: Define the specification's conformance model in the conformance clause.	Yes (p)
Good Practice 02: Specify in the conformance clause how to distinguish normative from informative content.		No
Good Practice 03: Provide the wording for conformance claims.		No
Good Practice 04: Provide an Implementation Conformance Statement Pro Forma.		No
Good Practice 05: Require an Implementation Conformance Statement as part of valid conformance claims.		No
2.2 Setting up ground rules
Requirement 02: Define the scope.	Yes
Good Practice 06: Provide examples, use cases, and graphics.	Yes
Good Practice 07: Write sample code or tests.	Yes
Requirement 03: Identify who or what will implement the specification.	Yes
Requirement 04: Make a list of normative references.	Yes
Good Practice 08: When imposing requirements by normative references, address conformance dependencies.	Yes (p)
2.3 Defining and using terminology
Requirement 05: Define the terms used in the normative parts of the specification.	Yes (p)
Requirement 06: Create conformance labels for each part of the conformance model.		No
Good Practice 09: Define the unfamiliar terms in-line, and consolidate the definitions in a glossary section.	Yes (p)
Good Practice 10: Use terms already defined without changing their definition.		No
Requirement 07: Use a consistent style for conformance requirements and explain how to distinguish them.	Yes (p)
Requirement 08: Indicate which conformance requirements are mandatory, which are recommended and which are optional.	Yes (p)
Good Practice 11: Use formal languages when possible.	Yes
Good Practice 12: Write Test Assertions.		No
2.4 Managing Variability
Good Practice 13: Create subdivisions of the technology when warranted.	Yes (p)
Requirement 09: If the technology is subdivided, then indicate which subdivisions are mandatory for conformance.	Yes
Requirement 10: If the technology is subdivided, then address subdivision constraints.	Yes (p)
Good Practice 14: If the technology is profiled, define rules for creating new profiles.		No
Good Practice 15:Use optional features as warranted.	Yes (p)
Good Practice 16: Clearly identify optional features.	Yes
Good Practice 17: Indicate any limitations or constraints on optional features.	Yes
Requirement 11: Address Extensibility.	Yes (p)
Good Practice 18: If extensibility is allowed, define an extension mechanism.		No
Good Practice 19: Warn extension creators to create extensions that do not interfere with conformance.		No
Good Practice 20: Define error-handling for unknown extensions.	Yes
Requirement 12: Identify deprecated features.	Yes (p)
Requirement 13: Define how each each class of product handles each deprecated feature.	Yes (p)
Good Practice 21: Explain how to avoid using a deprecated feature.		No
Good Practice 22: Identify obsolete features.	Yes
Good Practice 23: Define an error handling mechanism.	Yes

HTML 4.0.1

Guidelines	YES	NO	N/A	Comments
2.1 Specifying Conformance
Requirement 01: Include a conformance clause.	Yes
Good Practice 01: Define the specification's conformance model in the conformance clause.		No
Good Practice 02: Specify in the conformance clause how to distinguish normative from informative content.		No
Good Practice 03: Provide the wording for conformance claims.		No
Good Practice 04: Provide an Implementation Conformance Statement Pro Forma.		No
Good Practice 05: Require an Implementation Conformance Statement as part of valid conformance claims.		No
2.2 Setting up ground rules
Requirement 02: Define the scope.	Yes
Good Practice 06: Provide examples, use cases, and graphics.	Yes
Good Practice 07: Write sample code or tests.			N/A
Requirement 03: Identify who or what will implement the specification.		No
Requirement 04: Make a list of normative references.	Yes
Good Practice 08: When imposing requirements by normative references, address conformance dependencies.			N/A
2.3 Defining and using terminology
Requirement 05: Define the terms used in the normative parts of the specification.	Yes
Requirement 06: Create conformance labels for each part of the conformance model.		No
Good Practice 09: Define the unfamiliar terms in-line, and consolidate the definitions in a glossary section.	Yes
Good Practice 10: Use terms already defined without changing their definition.	Yes
Requirement 07: Use a consistent style for conformance requirements and explain how to distinguish them.	Yes
Requirement 08: Indicate which conformance requirements are mandatory, which are recommended and which are optional.	Yes
Good Practice 11: Use formal languages when possible.			N/A
Good Practice 12: Write Test Assertions.		No
2.4 Managing Variability
Good Practice 13: Create subdivisions of the technology when warranted.			N/A
Requirement 09: If the technology is subdivided, then indicate which subdivisions are mandatory for conformance.			N/A
Requirement 10: If the technology is subdivided, then address subdivision constraints.			N/A
Good Practice 14: If the technology is profiled, define rules for creating new profiles.			N/A
Good Practice 15:Use optional features as warranted.			N/A
Good Practice 16: Clearly identify optional features.			N/A
Good Practice 17: Indicate any limitations or constraints on optional features.			N/A
Requirement 11: Address Extensibility.		No
Good Practice 18: If extensibility is allowed, define an extension mechanism.			N/A
Good Practice 19: Warn extension creators to create extensions that do not interfere with conformance.			N/A
Good Practice 20: Define error-handling for unknown extensions.	Yes
Requirement 12: Identify deprecated features.	Yes
Requirement 13: Define how each each class of product handles each deprecated feature.	Yes
Good Practice 21: Explain how to avoid using a deprecated feature.	Yes
Good Practice 22: Identify obsolete features.	Yes
Good Practice 23: Define an error handling mechanism.	Yes

Semantic Interpretation for Speech Recognition

Guidelines	YES	NO	N/A	Comments
2.1 Specifying Conformance
Requirement 01: Include a conformance clause.	Yes
Good Practice 01: Define the specification's conformance model in the conformance clause.	Yes			For processors and for documents. Section 2 being called normative references and conformance, when it is another section that covers conformance, could be cleaned up a little.
Good Practice 02: Specify in the conformance clause how to distinguish normative from informative content.	Yes
Good Practice 03: Provide the wording for conformance claims.		No
Good Practice 04: Provide an Implementation Conformance Statement Pro Forma.		No
Good Practice 05: Require an Implementation Conformance Statement as part of valid conformance claims.		No
2.2 Setting up ground rules
Requirement 02: Define the scope.	Yes
Good Practice 06: Provide examples, use cases, and graphics.		No		There are examples and use cases, but no graphics, which would have been a nice thing to explain some points
Good Practice 07: Write sample code or tests.	Yes			Only the examples in the spec. This is sufficient for a last call document, but this work should be done to allow a reasonable demonstration of interoperability at any more advanced stage in the specifications development.
Requirement 03: Identify who or what will implement the specification.	Yes
Requirement 04: Make a list of normative references.	Yes
Good Practice 08: When imposing requirements by normative references, address conformance dependencies.			N/A
2.3 Defining and using terminology
Requirement 05: Define the terms used in the normative parts of the specification.		No		No glossary.
Requirement 06: Create conformance labels for each part of the conformance model.	Yes
Good Practice 09: Define the unfamiliar terms in-line, and consolidate the definitions in a glossary section.		No		There are some practical explanations, but no glossary.
Good Practice 10: Use terms already defined without changing their definition.			N/A	There doesn't seem to be much special use of terms.
Requirement 07: Use a consistent style for conformance requirements and explain how to distinguish them.	Yes			RFC 2119.
Requirement 08: Indicate which conformance requirements are mandatory, which are recommended and which are optional.	Yes (p)			But it isn't lovely to tease it out. Not clearly listed in a single place.
Good Practice 11: Use formal languages when possible.	Yes
Good Practice 12: Write Test Assertions.	Yes			Only the examples in the spec. This is sufficient for a last call document, but this work should be done to allow a reasonable demonstration of interoperability at any more advanced stage in the specifications development.
2.4 Managing Variability
Good Practice 13: Create subdivisions of the technology when warranted.	Yes			This is in fact a subdivision of the VoiceXML family of technology.
Requirement 09: If the technology is subdivided, then indicate which subdivisions are mandatory for conformance.	Yes
Requirement 10: If the technology is subdivided, then address subdivision constraints.	Yes
Good Practice 14: If the technology is profiled, define rules for creating new profiles.			N/A	There doesn't seem to be any possibility to define new profiles.
Good Practice 15:Use optional features as warranted.			N/A	Cannot tell if the option to use ABNF or XML is justified. It just seems to be claimed by the group.
Good Practice 16: Clearly identify optional features.			N/A
Good Practice 17: Indicate any limitations or constraints on optional features.			N/A
Requirement 11: Address Extensibility.		No		It is noted as something that is likely to happen, in the section on conformance. But it is not actually addressed.
Good Practice 18: If extensibility is allowed, define an extension mechanism.			N/A
Good Practice 19: Warn extension creators to create extensions that do not interfere with conformance.			N/A
Good Practice 20: Define error-handling for unknown extensions.	Yes
Requirement 12: Identify deprecated features.	Yes
Requirement 13: Define how each each class of product handles each deprecated feature.	Yes
Good Practice 21: Explain how to avoid using a deprecated feature.	Yes
Good Practice 22: Identify obsolete features.	Yes
Good Practice 23: Define an error handling mechanism.	Yes

XML:id

Guidelines	YES	NO	N/A	Comments
2.1 Specifying Conformance
Requirement 01: Include a conformance clause.	Yes
Good Practice 01: Define the specification's conformance model in the conformance clause.
Good Practice 02: Specify in the conformance clause how to distinguish normative from informative content.
Good Practice 03: Provide the wording for conformance claims.
Good Practice 04: Provide an Implementation Conformance Statement Pro Forma.
Good Practice 05: Require an Implementation Conformance Statement as part of valid conformance claims.
2.2 Setting up ground rules
Requirement 02: Define the scope.	Yes			Could be improved by creating a scope section with a specific Table of content item, for example "1.1 Scope"
Good Practice 06: Provide examples, use cases, and graphics.
Good Practice 07: Write sample code or tests.
Requirement 03: Identify who or what will implement the specification.	Yes			In the introduction explain that the xml:id specification gives a uniform mechanism for XML processors and XML document to create identifiers for XML Schema and DTD.
Requirement 04: Make a list of normative references.	Yes
Good Practice 08: When imposing requirements by normative references, address conformance dependencies.
2.3 Defining and using terminology
Requirement 05: Define the terms used in the normative parts of the specification.	Yes			A section terminology defines the main terms.
Requirement 06: Create conformance labels for each part of the conformance model.	Yes			It could be improved by defining a precise label like "xml:id conformant"
Good Practice 09: Define the unfamiliar terms in-line, and consolidate the definitions in a glossary section.
Good Practice 10: Use terms already defined without changing their definition.
Requirement 07: Use a consistent style for conformance requirements and explain how to distinguish them.	Yes			The specification is using the terms of RFC2119 as a way to define the requirements.
Requirement 08: Indicate which conformance requirements are mandatory, which are recommended and which are optional.		No		There are a few "RFC2119:SHOULD" in your specification in the section 4. Though the conformance section doesn't explain if a conformant XML Processor have to implement all MUST only or MUST and SHOULD. This could be also solved by making a Basic Level and a Full level of Conformance. Or just indicate that the "MUST" MUST be implemented to be conformant.
Good Practice 11: Use formal languages when possible.
Good Practice 12: Write Test Assertions.
2.4 Managing Variability
Good Practice 13: Create subdivisions of the technology when warranted.
Requirement 09: If the technology is subdivided, then indicate which subdivisions are mandatory for conformance.			N/A	The specification is monolithic and done to be used in other technologies.
Requirement 10: If the technology is subdivided, then address subdivision constraints.			N/A	See Requirement 09.
Good Practice 14: If the technology is profiled, define rules for creating new profiles.
Good Practice 15:Use optional features as warranted.
Good Practice 16: Clearly identify optional features.
Good Practice 17: Indicate any limitations or constraints on optional features.
Requirement 11: Address Extensibility.	Yes			This mechanism is an extension of other mechanisms. Though you could just answer the warn the readers/implementers that it's a mechanism that it's not extensible at all. xml:id is defined as it is.
Good Practice 18: If extensibility is allowed, define an extension mechanism.
Good Practice 19: Warn extension creators to create extensions that do not interfere with conformance.
Good Practice 20: Define error-handling for unknown extensions.
Requirement 12: Identify deprecated features.			N/A	There's no previous version of this document.
Requirement 13: Define how each each class of product handles each deprecated feature.			N/A	See Requirement 12.
Good Practice 21: Explain how to avoid using a deprecated feature.
Good Practice 22: Identify obsolete features.
Good Practice 23: Define an error handling mechanism.

SVG 1.1

Guidelines	YES	NO	N/A	Comments
2.1 Specifying Conformance
Requirement 01: Include a conformance clause.	Yes
Good Practice 01: Define the specification's conformance model in the conformance clause.	Yes
Good Practice 02: Specify in the conformance clause how to distinguish normative from informative content.		No
Good Practice 03: Provide the wording for conformance claims.		No
Good Practice 04: Provide an Implementation Conformance Statement Pro Forma.		No
Good Practice 05: Require an Implementation Conformance Statement as part of valid conformance claims.		No
2.2 Setting up ground rules
Requirement 02: Define the scope.	Yes
Good Practice 06: Provide examples, use cases, and graphics.	Yes
Good Practice 07: Write sample code or tests.	Yes
Requirement 03: Identify who or what will implement the specification.	Yes
Requirement 04: Make a list of normative references.	Yes
Good Practice 08: When imposing requirements by normative references, address conformance dependencies.			N/A
2.3 Defining and using terminology
Requirement 05: Define the terms used in the normative parts of the specification.	Yes
Requirement 06: Create conformance labels for each part of the conformance model.	Yes
Good Practice 09: Define the unfamiliar terms in-line, and consolidate the definitions in a glossary section.	Yes
Good Practice 10: Use terms already defined without changing their definition.			N/A
Requirement 07: Use a consistent style for conformance requirements and explain how to distinguish them.	Yes
Requirement 08: Indicate which conformance requirements are mandatory, which are recommended and which are optional.	Yes
Good Practice 11: Use formal languages when possible.	Yes
Good Practice 12: Write Test Assertions.		No
2.4 Managing Variability
Good Practice 13: Create subdivisions of the technology when warranted.	Yes
Requirement 09: If the technology is subdivided, then indicate which subdivisions are mandatory for conformance.			N/A
Requirement 10: If the technology is subdivided, then address subdivision constraints.			N/A
Good Practice 14: If the technology is profiled, define rules for creating new profiles.		No
Good Practice 15:Use optional features as warranted.			N/A
Good Practice 16: Clearly identify optional features.	Yes
Good Practice 17: Indicate any limitations or constraints on optional features.			N/A
Requirement 11: Address Extensibility.	Yes
Good Practice 18: If extensibility is allowed, define an extension mechanism.	Yes
Good Practice 19: Warn extension creators to create extensions that do not interfere with conformance.		No
Good Practice 20: Define error-handling for unknown extensions.		No
Requirement 12: Identify deprecated features.		No
Requirement 13: Define how each each class of product handles each deprecated feature.		No
Good Practice 21: Explain how to avoid using a deprecated feature.			N/A
Good Practice 22: Identify obsolete features.			N/A
Good Practice 23: Define an error handling mechanism.	Yes

Spec?

Guidelines	YES	NO	N/A	Comments
2.1 Specifying Conformance
Requirement 01: Include a conformance clause.
Good Practice 01: Define the specification's conformance model in the conformance clause.
Good Practice 02: Specify in the conformance clause how to distinguish normative from informative content.
Good Practice 03: Provide the wording for conformance claims.
Good Practice 04: Provide an Implementation Conformance Statement Pro Forma.
Good Practice 05: Require an Implementation Conformance Statement as part of valid conformance claims.
2.2 Setting up ground rules
Requirement 02: Define the scope.
Good Practice 06: Provide examples, use cases, and graphics.
Good Practice 07: Write sample code or tests.
Requirement 03: Identify who or what will implement the specification.
Requirement 04: Make a list of normative references.
Good Practice 08: When imposing requirements by normative references, address conformance dependencies.
2.3 Defining and using terminology
Requirement 05: Define the terms used in the normative parts of the specification.
Requirement 06: Create conformance labels for each part of the conformance model.
Good Practice 09: Define the unfamiliar terms in-line, and consolidate the definitions in a glossary section.
Good Practice 10: Use terms already defined without changing their definition.
Requirement 07: Use a consistent style for conformance requirements and explain how to distinguish them.
Requirement 08: Indicate which conformance requirements are mandatory, which are recommended and which are optional.
Good Practice 11: Use formal languages when possible.
Good Practice 12: Write Test Assertions.
2.4 Managing Variability
Good Practice 13: Create subdivisions of the technology when warranted.
Requirement 09: If the technology is subdivided, then indicate which subdivisions are mandatory for conformance.
Requirement 10: If the technology is subdivided, then address subdivision constraints.
Good Practice 14: If the technology is profiled, define rules for creating new profiles.
Good Practice 15:Use optional features as warranted.
Good Practice 16: Clearly identify optional features.
Good Practice 17: Indicate any limitations or constraints on optional features.
Requirement 11: Address Extensibility.
Good Practice 18: If extensibility is allowed, define an extension mechanism.
Good Practice 19: Warn extension creators to create extensions that do not interfere with conformance.
Good Practice 20: Define error-handling for unknown extensions.
Requirement 12: Identify deprecated features.
Requirement 13: Define how each each class of product handles each deprecated feature.
Good Practice 21: Explain how to avoid using a deprecated feature.
Good Practice 22: Identify obsolete features.
Good Practice 23: Define an error handling mechanism.