[Ed. Although it should be usable, this is still an editor's draft, with some embedded editor's comments, styled like this.]
As explained in the Status section of an earlier Specification Guidelines (SpecGL) document, after reaching CR, SpecGL was substantially revised and redesigned for simplicity, user-friendliness, and usability. A big part of achieving those goals is providing tools and templates to facilitate and accelerate spec authors' work. This is an illustration, and usable version, of a principal such tool/template -- the Conformance Clause Template.
Eventually, the principal version of such a template will be an interactive form -- an incomplete sample illustrates this.
Authors' caveat. For the purposes of the 17 August 2005 Recommendation publication of SpecGL, this version of the template is reasonably well aligned. A more user-friendly and usable version is being produced.
This template is one of a collection of documents about how to make specifications clearer, more precise, and more testable. It provides a template for authors to use in constructing Conformance Clause sections for their specifications. Clear conformance specifications in a good Conformance Clause is the probably the single biggest enabler of clear, testable specifications and interoperable implementations.
The other currently existing member of the collection is QA Framework: Specification Guidelines (SpecGL). SpecGL defines both a normative set of rules and recommended practices about specification authoring, in the form of helpful and non-authoritarian Principles and Good Practice advice.
This template companion to SpecGL is defined so that specification authors should be able to start in either document and find most of the useful advice and benefit of the SpecGL collection.
This template is one easy way to satisfy the rules and guidelines of SpecGL. It is not the only way, and SpecGL users may implement other successful strategies of their own chosing. This template also contains markup of its sub-sections [TBD] -- use of it will enable the application of tools [TBD] provided by the QA Activity, that assist conformance verification and other useful tasks related to SpecGL.
[Ed note. Adding div/class markup to this template is yet tbd.]
SpecGL contains lots of examples. To improve its usability, this template contain a few links to examples from each one of the template sections. [Ed note. TBD. Is it going to contain example links? It would probably help user complete the template item.]
Legend:
[Having a Conformance Clause like this satisfies Requirement 01] [Quick examples: @@Example 1@@; @@Example 2@@; @@Example 3@@]
[Ed note. This version of the CC template is written in the manner of a "virtual conformance clause", about a fictitious FooML, rather than classical "template" style. This is done for illustration purposes. The ultimate form is yet TBD.]
"All important information about conformance to FooML can be found starting here in this Conformance Clause."
[Having a Conformance Clause like this satisfies Requirement 01]
[Quick examples: @@Example 1@@; @@Example 2@@; @@Example 3@@]
"The normative parts of this specification are identified by:" [Note to template user: here you should described how normative bits are distinguished from informative bits in the specification: choose one or more of { markup | section labelling | enumeration here | other (specify) }.
[Distinguishing normative/informative content satisfies Good Practice 02 ]
[Quick examples: @@Example 1@@; @@Example 2@@; @@Example 3@@]
"The language and method of expression used for individual conformance requirements or testable statements in this specification is:" Note to template user: choose all that apply...
[Note to template user: especially if RFC2119 is not used, here also you should address the "manditoriness" of conformance requirements, e.g., whether they are manditory, recommended, or optional.]
[Defining the language/style/markup and "manditoriness" for testable requirements satisfies Requirement 07, Requirement 08 ]
[Quick examples: @@Example 1@@; @@Example 2@@; @@Example 3@@]
"The conformance model of FooML is defined collectively by:
[Addressing these aspects in a conformance model section satisfies Good Practice 01]
[Note to template user: each group of similar things that may conform is known as a @@Class of Product@@ -- things like FooML instances, FooML generators, FooML parsers, FooML interpreters, etc., each are a Class of Product.]
"This FooML specification defines conformance for:"
"Each of the following subsections discusses and defines one of the CoP of FooML in more detail. In particular, they give the high-level view of the criteria for conformance to each CoP of FooML."
[Note to template user: Include such a subsection for each Class of Product.]
[Identifying things for which FooML defines conformance satisfies Requirement 03]
[Quick examples: @@Example 1@@; @@Example 2@@; @@Example 3@@]
"This specification uses these conformance designations:" [Note to template user: complete this section, referencing common conformance concepts from SpecGL or other literature, and defining any new concepts that may be invented and used in the specification.]
"The conformance labels used by this specification are:" [Note to template user: complete this section, as explained in Requirement 06 of SpecGL, defining any new concepts that may be invented and used.]
[Identifying conformance designations satisfies Good Practice 01, and conformance labels satisfies Requirement 06]
[Quick examples: @@Example 1 WCAG10 A/AA/AAA@@; @@Example 2 SVG static/dynamic(?)@@; @@Example 3@@]
"FooML {does | doesn't } address and define profiles to subdivide the technology."
[Note to template user: If "doesn't", this section is optional, but it doesn't hurt to be explicit about it. If "does", then describe the scheme, subdivisions, targetted application sectors, any constraints, etc. of any profiles defined by FooML]
[Addressing these aspects of FooML's use of profiles satisfies Good Practice 13, Requirement 09, Requirement 10]
"FooML {does | doesn't } address and define rules for profiles, which establish FooML's definition of what comprises a valid profile."
[Note to template user: If "doesn't", this section is optional. If "does", then describe the scheme, subdivisions, targetted application sectors, any constraints, etc.]
[Addressing whether FooML defines rules for satisfies Good Practice 14]
[Quick examples: @@Example 1@@; @@Example 2)@@; @@Example 3@@]
"FooML {does | doesn't } address and define modules to subdivide the technology."
[Note to template user: If "doesn't, this section is optional, but it doesn't hurt to be explicit about it. If "does", then describe the scheme, enumerate the subdivisions, targetted application sectors, any constraints, etc.]
[Addressing these aspects of FooML's use of modules satisfies Good Practice 13, Requirement 09, Requirement 10]
[Quick examples: @@Example 1@@; @@Example 2)@@; @@Example 3@@]
"FooML {does | doesn't } address and define levels to subdivide the technology."
[Note to template user: If "doesn't", this section is optional, but it doesn't hurt to be explicit about it. If "does", then describe the scheme, enumerate subdivisions, targetted application sectors, any constraints, etc.]
[Addressing these aspects of FooML's use of levels satisfies Good Practice 13, Requirement 09, Requirement 10]
[Quick examples: @@Example 1@@; @@Example 2)@@; @@Example 3@@]
"FooML {does | doesn't } deprecate features from previous version(s)."
[Note to template user: If "doesn't, this section is optional, but it doesn't hurt to be explicit about it. If "does", then list & describe, or provide links to, all of the deprecated features of the specification. Here or at linked locations, describe the conformance requirements each deprecated item for each affected CoP.]
[Identifying and describing here, or here linking to, these aspects of any deprecation in FooML satisfies Requirement 12, Requirement 13, Good Practice 21]
[Quick examples: @@Example 1 MathML@@; @@Example 2)@@; @@Example 3@@]
"FooML {has | hasn't } made features from previous version(s) obsolete."
[Note to template user: If "doesn't, this section is optional, but it doesn't hurt to be explicit about it. If "has", then list & describe all of the obsolete features of the specification.]
[Identifying any obsolete features of FooML satisfies Good Practice 22 ]
[Quick examples: @@Example 1 MathML@@; @@Example 2)@@; @@Example 3@@]
"FooML {does | doesn't } allow any discretionary items."
[Note to template user: If "doesn't, this section is optional, but it doesn't hurt to be explicit about it. If "does", then list & describe, or provide links to, all of the discretionary items of the specification.]
[Identifying and describing discretionary items in FooML satisfies Good Practice 15, Good Practice 16, Good Practice 17]
[Quick examples: @@Example 1@@; @@Example 2)@@; @@Example 3@@]
"FooML { is | is not} extensible".
[Stating FooML's extensibility policy satisfies Requirement 11.]
[Note to template user: If "is", then complete the following:
[Addressing these aspects of FooML's extensibility policy satisfies Good Practice 19, Good Practice 18]
[Quick examples: @@Example 1@@; @@Example 2)@@; @@Example 3@@]
Completing the above information in FooML's conformance clause satisfies Good Practice 03 .]
[Quick examples: @@Example 1@@; @@Example 2)@@; @@Example3@@]
[Providing a FooML ICS pro-forma satisfies Good Practice 04, and requiring its usage in conformance claims satisfies Good Practice 05 ]
[Quick examples: @@Example 1@@; @@Example 2)@@; @@Example 3@@]