SpecLite -- Template(s)

Contents

• Introduction
• A usable "Scope" template
• Conformance Clause for FooML (template)
  • Finding FooML's normative content
  • FooML's Conformance model
  • FooML defines conformance for...
  • Conformance designations
  • Ways that conforming FooML implementations may differ
    • Profiles
    • Modules
    • Levels
    • Deprecated features
    • Discretionary items
    • Extensibility
  • Conformance claims

Introduction

[Ed note. This is a companion draft proposal toSpecLite -- checklist.]

The SpecLite triad

This is one of a trio of documents about how to make your specifications clearer, more precise, and more testable. The other two are @@SpecLite -- Guidelines@@, and @@SpecLite -- Examples & Techniques@@. Though SpecGL defines the normative set of rules for the topics of SpecLite, the trio is crafted in such a way that you can start with any one and easily find the related parts of the others.

Satisfying SpecLite-GL the easy way

This template (??or these templates??) is one easy way to satisfy the rules and guidelines of SpecGL. It is not the only way, and SpecLite 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@@ offered by the QA Activity, that assist conformance verification and other useful tasks related to SpecLite.

[Ed note. Adding div/class markup to this template is yet tbd.]

Key to the templates

SpecET contains detailed treatment and discussion of examples, and sometimes alternate techniques. To improve their usability, this/these template(s) contain a few links to examples from each one of the template sections.

Legend:

• [Ed note. ...blah...blah...] Temporary editorial notes from the author, to be removed in the process of coming up with a final version of this/these template(s).
• [Satisfies ... GL/CPx.y; ...etc...] -- a link from this part of the template to that part of SpecGL that it implements, plus quick examples and other nice user aids. [Ed note. GL or CP or Principal or whatever we decide to call the rules ... tbd.] May/should be deleted by template users.]
• [...blah...] -- other stuff in square brackets are directed at the user of this template.
• "..." -- prototype wording which could be included directly in the template.
• bullet lists -- bullet lists within subsections are mostly for organization purposes of this outline. They are not necessarily implied to be part of the template produced from this outline, or a CC produced from the template by the template user.
• section headings -- these are, verbatim, the suggested headings for the template, and for user's Conformance Clause that results from using the template
• "@@...@@" generally indicates link to outside documents or resources.

Scope specifications for FooML

[Ed note. Although the CC template gives by far the most return for the effort, I think also a Scope template would be interesting, and it could pinch the stuff from ISO Directives Part 3 for its content. I haven't decided whether it ought to be a separate template (probably), but for this first cut I'm combining 'em..]

...tbd...

[Having a scope definition early in the FooML specification satisfies @@GL/CPx.y@@] [Quick examples: @@Example 1@@; @@Example 2@@; @@Example 3@@] [@@Detailed examples & techniques.@@]

Conformance Clause for FooML

[Ed note. I'm writing this is the manner of a "virtual conformance clause", about a fictitious FooML, for early-draft illustration purposes; rather than classical "template" style.]

"Everything that you need to know about conformance to FooML can be found starting here in this Conformance Clause."

[Having a conformance clause like this satisfies @@GL/CPx.y@@] [Quick examples: @@Example 1@@; @@Example 2@@; @@Example 3@@] [@@Detailed examples & techniques.@@]

Finding FooML's normative content

Normative & Informative parts

"The normative parts of this specification are identified by:" [here the template user should described how normative from informative bits are identified in the rest of the specification; choice of { markup | section labelling | enumeration here | other (specify) }.

[Distinguishing normative/informative content satisfies @@GL/CPx.y@@] [Quick examples: @@Example 1@@; @@Example 2@@; @@Example 3@@] [@@Detailed examples & techniques.@@]

Normative language

"The language and method of expression used for individual conformance requirements or testable statements in this specification is:" [TBD update the following...]

• either RFC2119
  • include normal boiler plate
• or "other"
  • describe the method;

[Defining the language/style/markup for testable requirements satisfies @@GL/CPx.y@@] [Quick examples: @@Example 1@@; @@Example 2@@; @@Example 3@@] [@@Detailed examples & techniques.@@]

FooML's Conformance model

"The conformance model of FooML is defined by a combination of:

• specifying what may conform and how
• any designations or concepts used to categorize conformance
• any ways in which conforming implementations may vary from each other"

FooML defines conformance for...

[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.]

[Ed note. Might (or might not) want to get rid of CoP terminology and replace it w/ something more common. But it is a convenient handle for now.]

"This FooML specification defines conformance for:"

• [CoP1: briefly describe what it is]
• [CoP2: briefly describe what it is]
• ...etc...

"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."

[Identifying things for which FooML defines conformance satisfies @@GL/CPx.y@@] [Quick examples: @@Example 1@@; @@Example 2@@; @@Example 3@@] [@@Detailed examples & techniques.@@]

Conformance designations

[Ed note. We have something here that we believe (according to discussions during SpecGL TAs) is worthwhile, but we have had a bit of trouble nailing it down. It subsumes the following two bits from old SpecGL and the associated checkpoints.

"This specification uses these conformance concepts:" [explain/instruct template user to 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.] [Satisfies CP8.2]

"The conformance designations used by this specification are:" [explain/instruct template user to 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.] [Satisfies CP8.5]

]

[Identifying ...this...satisfies @@GL/CPx.y@@] [Quick examples: @@Example 1 WCAG10 A/AA/AAA@@; @@Example 2 SVG static/dynamic(?)@@; @@Example 3@@] [@@Detailed examples & techniques.@@]

Ways that conforming FooML implementations may differ

• "FooML explicitly allows conforming implementations to vary in these ways: [choice list including: Profiles, Modules, Levels, Deprecated Features, Discretionary Items, Extensibility.]

Profiles

"FooML {does | doesn't } address and define profiles to subdivide the technology."

[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]

"FooML {does | doesn't } address and define rules for profiles, which establish FooML's definition of what comprises a valid profile."

[If "doesn't, this section is optional. If "does", then describe the scheme, subdivisions, targetted application sectors, any constraints, etc.]

[Identifying FooML's use of profiles satisfies @@GL/CPx.y@@] [Quick examples: @@Example 1@@; @@Example 2)@@; @@Example 3@@] [@@Detailed examples & techniques.@@]

Modules

"FooML {does | doesn't } address and define modules to subdivide the technology."

[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.]

[Identifying FooML's use of modules satisfies @@GL/CPx.y@@] [Quick examples: @@Example 1@@; @@Example 2)@@; @@Example 3@@] [@@Detailed examples & techniques.@@]

Levels

"FooML {does | doesn't } address and define levels to subdivide the technology."

[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.]

[Identifying FooML's use of levels satisfies @@GL/CPx.y@@] [Quick examples: @@Example 1@@; @@Example 2)@@; @@Example 3@@] [@@Detailed examples & techniques.@@]

Deprecated features

"FooML {does | doesn't } deprecate features from previous version(s)."

[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 affectedCoP.]

[Identifying and describing any deprecation in FooML satisfies @@GL/CPx.y@@] [Quick examples: @@Example 1 MathML@@; @@Example 2)@@; @@Example 3@@] [@@Detailed examples & techniques.@@]

Obsolete features

[Ed note. Haven't decided whether or not to have this at all, fold it into previous at GL/CP level, fold it in at template level, fold it in at the ET level, etc.]

Discretionary items

"FooML {does | doesn't } allow any discretionary items."

[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 @@GL/CPx.y@@] [Quick examples: @@Example 1@@; @@Example 2)@@; @@Example 3@@] [@@Detailed examples & techniques.@@]

Extensibility

"FooML { is | is not} extensible".

[If "is":

• [Ed note. Check out and select smaller subset of extensibility rules, tbd, but maybe...]
• "The valid use of extensions as permitted and described by this specification shall not negate or contradict standardized, defined functionality of this specification." [maybe]
• "FooML defines the following standardized mechanism and syntax by which a statement by which extensions are expressed, invoked, etc: [do it]". [yes]
• "FooML {does | does not} require -- accompanying valid invocations of extensibility -- features, alternatives, etc that mitigate the interoperability impacts of the extensions. [If "does", elaborate.] " [maybe]

]

[Identifying and describing extensibility policy in FooML satisfies @@GL/CPx.y@@] [Quick examples: @@Example 1@@; @@Example 2)@@; @@Example 3@@] [@@Detailed examples & techniques.@@]

Conformance claims

• "Valid [Ed. note...well-formed?] conformance claims about FooML must include at least the following:
  • [fill-in spec name]
  • [fill-in spec version]
  • [fill-in degree of conformance claimed]
  • [fill-in identifying information about subject of conformance claim]
  • [fill-in date of claim]
  • [fill-in pointer to ICS supporting claim, if appropriate] "

[Ed note. Undecided whether to include the ICS pro-forma stuff here, there, neither, optional etc. I think "not" for GL/CP, but maybe bring it up in SpecET as a good supplemental thing to do.]

• [choice-of-two, explain/instruct the template user to complete one of the following;]
  • "A suitable Implementation Conformance Statement (ICS) pro-forma for this specification may be found at:" [instruct template user to provide link, or provide material in-line]
  • "The use of Implementation Conformance Statements is inapplicable with this specification because:" [instruct template user to finish the statement, by providing the justification for n/a]

[Addressing FooML's conformance claim policy satisfies @@GL/CPx.y@@] [Quick examples: @@Example 1@@; @@Example 2)@@; @@Example 3@@] [@@Detailed examples & techniques.@@]