SpecGL: comments on Guideline A

Here is the first installment......Most of this is editorial, cleaning up 
grammar, clarifying text, hopefully improving Karl's excellent production 
(and contributions from Lofton, Dom and Mark)

Suggest changing the numbering system to numbers rather than letters  so A 
becomes 1 Specifying Conformance.  A.1 becomes 1.1.  The first Principle 
becomes
A1.1 Principle A
A1.1 Principle B
Etc.


General Comment
I’m finding the following terms confusing  Conformance policy, conformance 
mode, conformance landscape  are they the same or different?

Also, We need to go through all the Techniques and Examples.


Guidelines: A1 Specifying Conformance

1. 1st paragraph
- Remove ‘ultimately’
-Suggest replacing 2nd sentence:  The conformance model, its description 
and the language used to convey normative information not only determines 
the testability of a specification, but also influences the overall 
implementation landscape  e.g., multiple flavors of conformance resulting 
in numerous, fragmented, conforming implementations or a limited flavors of 
conformance resulting in few allowable variations among implementations.
-last sentence, 2nd paragraph:  /satisfied to claim/satisfied in order to 
claim/

2.  A.1. A conformance clause is essential
-1st sentence:  /to full conformance/to achieving conformance/
-3rd paragraph, Suggest replacing:
For some specifications, the conformance model may be straightforward and 
simple, and the conformance clause template [link] when completed, may 
provide most of the information needed in a conformance clause.  For 
others, the conformance model will be complex or convoluted, and the 
advanced details … may be invaluable in creating the conformance clause.

3. Principle: Include a conformance clause
- What does this mean?
Suggest rewording:
For starters, it is the root source from which readers can find any 
conformance-related information.  The conformance clause provides the 
answer to the all important question: What may conform and how? The 
conformance clause defines at a high-level, what is required of 
implementers of the specification.  It, in turn can refer to other parts of 
the specification or other specifications.  The conformance clause may 
partition the technology into functional subsets, such as profiles, modules 
or other structures.  Additionally, it may specify minimal requirements for 
certain functions, as well as the permissibility of extensions, options and 
alternative approaches and how they are to be handled.

-Why care?
This currently says to have a conformance clause so you can conform to 
SpecGL.  The argument should convince people to have a clause, irrespective 
of SpecGL.
Suggest: The conformance clause provides a common understanding of what is 
required to claim conformance.  It provides communication between the 
standards developers, implementers, and users as to what is required, and 
gives meaning to the phrase, ‘conforming implementation’.  Moreover, it 
facilitates the consistent application of conformance within a 
specification and across related specifications.  It promotes 
interoperability.

-Techniques
1st bullet:  s/must/need to/
2nd bullet: /Create a item/Create an item/
3rd bullet: /is made of/consists of/

-Examples
/gives an example/is an example/
/gives a detailed/contains a detailed/

4. Good Practice: Define the specification’s [add the ‘s]
2nd bullet  conformance categories is unclear  the e.g, implies categories 
= subdivisions.  But, do we mean categories = different flavors as implied 
by the examples, e.g., well formed/valid and validating/non-validating.
Suggest: Any special designations or concepts used to distinguish 
conformance categories, flavors, etc. (e.g., profile/module/level, 
well-formed/valid, A/AA/AAA)

-Why care
This needs to be rewritten (already a recorded Issue).
Suggest including: The key is to communicate to the reader what conformance 
to the specification is all about.  It provides a framework for 
implementers to know what they need to build in order to conform and the 
different ways that they could claim conformance.  It provides users/buyers 
a basis to express their requirements.

- Techniques;
This may be too Profile/Level/Module focused.
#1 Thought we were going to stay away from the term DoV.

5. GP: Specify in the conformance clause how to distinguish normative….
-Why care
Reword:  Conformance of implementations is defined by and measured against 
normative content.  Distinguishing normative content from that which is 
informative helps to make sure the reader can find the normative content, 
knows for sure that it is normative, and doesn’t fail to notice a normative 
section.  This good practice is aimed at the high level partitioning of 
information (e.g., sections) in a specification.

-Techniques
Combine #1 and 2.  Suggest:
For each section in the specification, determine if the content is 
normative or informative and the, explicitly label it as either ‘normative’ 
or ‘informative’.  Make the label part of the section heading (e.g., 
Informative References), as parenthetical text with the heading (e.g., 
Glossary (normative)), or create a list of each section and indicate its 
normality, (e.g., this document’s conformance section’s Normative Parts).

#3  grammar/typo correction
In the conformance clause, explain what the use and meaning (if necessary) 
of the words used to convey the normality and informality of the content.

#4
/avoid a language/avoid language/