Re: [SpecGL Draft] A.1 Principle: Include a conformance clause

>A.1 Conformance clause is "paramount"
>
>With a good conformance clause, a specification comes close to full 
>conformance to this Specification Guidelines.
>
>         """KD: I would like to know what was the meaning
>         of paramount in this context, and I think
>         we would like to change it because I don't see
>         how to translate the concepts in other languages.
>         It might be difficult to understand. Any suggestions?"""

possible substitutions for paramount is: fundamental or essential



>         """KD: Moved this section out of the principle to put it
>         here as an intro."""
>
>The conformance section of a specification -- commonly called the 
>Conformance Clause -- is a high-level description of what is required of 
>implementers and application developers. It, in turn, may refer to other 
>parts of the specification for some details. Ideally, it is the root 
>source from which readers can find any conformance-related information.
>
>For some specifications, the conformance landscape may be plain and 
>simple, and the conformance clause template may be almost all that is 
>needed [Example?]. For others, the conformance landscape will be complex 
>or convoluted, and the advanced details and topics of these specification 
>guidelines -- topics like multiple intersecting Dimensions of Variability 
>-- may be invaluable.

careful using Dimensions of Variability, since this is not fully described 
in the document - perhaps not capitalizing DoV will work or better yet 
refer to the section on Managing Variability (section D)

>Principle:
>         Include a conformance clause.
>
>What does it mean?
>         For starters, the conformance clause needs to answer the 
> all-important question: what may conform and how? It may, for conformance 
> purposes, partition the technology into functional subsets, such as 
> profiles, levels, or other structures. Additionally it may specify the 
> permissibility of extensions, options, and alternative approaches and how 
> they are to be handled.
>
>Why care?
>         A well done conformance clause brings most of the benefit of 
> these specification guidelines for the least effort. Almost all of 
> SpecGL's significant advice -- normative Principles and recommended Good 
> Practices alike -- are satisfied with a good conformance clause.

s/done/constructed/
awkward.  Suggest:  A well constructed conformance achieves almost all the 
benefits advocated by these specification guidelines.


>Technique
>         1. Simple, complete the conformance clause template and put the 
> result into the specification.
>
>         """KD: Do we have a conformance template?"""

Lofton is working on something as part of the NIST deliverable.  He should 
have something soon.

>To be honest, answering the questions in the conformance clause template 
>may not be a simple matter, and may lead the Working Group into thorny 
>issues. However, these are questions that must be answered if the 
>specification is to be successful, i.e., if it is to foster multiple high 
>quality interoperating implementations.
>         2. Create a item in the table of content for your conformance 
> section.
>         3. If your technology is made of multiple individual 
> recommendations, create a table of content item for Conformance, and 
> explain that the Conformance section is in another document.
>
>Examples
>
>         * Ruby
>         * SVG

Received on Tuesday, 3 August 2004 19:18:49 UTC