- From: Karl Dubost <karl@w3.org>
- Date: Wed, 8 Dec 2004 16:06:12 -0500
- To: public-xml-id@w3.org
- Message-Id: <FDDC01D7-495C-11D9-AD00-000A95718F82@w3.org>
XML WG,
I have tried to see if you were conformant to the 13 requirements of
SpecGL. I haven't checked the Good Practices but you can continue to
look (I joined them in this document) and try to see if you meet the
good practices criteria. It will just improve the quality of your
specification.
I have used SpecGL version of Nov 22, 2004 (LC) [1]
SpecGL is a tool to help you to improve the quality of your
specification. The new SpecGL is really easy to use and you might be
interested by reading it. There are plenty of step by step techniques.
[1] http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/
The Good News:
xml:id is almost conformant to QA SpecGL LC version Nov 22, 2004
if you modify the specification for
- 3.2.B "Indicate which conformance requirements
are mandatory, which are recommended and
which are optional."
- 4.3.A "Address Extensibility"
which are both really easy to meet. It's just a question of wording.
And that will mean that xml:id would be the ***first*** ever Spec
conformant to QA SpecGL. I would like to add that the section C on
impact on Other Standards is very welcome and answer a few questions of
the Good Practice 2.3.B "Do systematic reviews of normative references
and their implications."
The Bad News:
There's no bad news ;)
ICS Spec GL Version Nov 22, 2004
===============================
* 13 Requirements (Normative) *
===============================
1.1.A: Include a conformance clause.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#include-
conformance-clause-principle
YES/NO/Not Applicable: Explain why?
YES.
http://www.w3.org/TR/2004/WD-xml-id-20041109/#conformance
2.1.A: Define the scope.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#define-scope-
principle
YES/NO/Not Applicable: Explain why?
YES
http://www.w3.org/TR/2004/WD-xml-id-20041109/#intro
Though could be improved by creating a scope section with a specific
Table of content item, for example "1.1 Scope"
2.2.A: Identify who or what will implement the specification.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#implement-principle
YES/NO/Not Applicable: Explain why?
YES
http://www.w3.org/TR/2004/WD-xml-id-20041109/#intro
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.
2.3.A: Make a list of normative references.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#ref-norm-principle
YES/NO/Not Applicable: Explain why?
YES
http://www.w3.org/TR/2004/WD-xml-id-20041109/#references
3.1.A: Define the terms used in the normative parts of the
specification.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#define-terms-
principle
YES/NO/Not Applicable: Explain why?
YES
http://www.w3.org/TR/2004/WD-xml-id-20041109/#terminology
A section terminology defines the main terms.
3.1.B: Create conformance labels for each part of the conformance model.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#conf-label-principle
YES/NO/Not Applicable: Explain why?
YES
http://www.w3.org/TR/2004/WD-xml-id-20041109/#terminology
It could be improved by defining a precise label like "xml:id
conformant"
(Note that the 7.2 is confusing because usually in the conformance
section, we can find what we need to conform, and not necessary what
this specification conforms too. Maybe that would be better to put it
elsewhere.)
3.2.A: Use a consistent style for conformance requirements and explain
how to distinguish them.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#consistent-style-
principle
YES/NO/Not Applicable: Explain why?
YES
http://www.w3.org/TR/2004/WD-xml-id-20041109/#terminology
The specification is using the terms of RFC2119 as a way to define the
requirements.
3.2.B: Indicate which conformance requirements are mandatory, which are
recommended and which are optional.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#req-opt-conf-
principle
YES/NO/Not Applicable: Explain why?
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.
4.1.B: If the technology is subdivided, then indicate which
subdivisions are mandatory for conformance.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#subdivide-
mandatory-principle
YES/NO/Not Applicable: Explain why?
Not Applicable.
The specification is monolithic and done to be used in other
technologies.
4.1.C: If the technology is subdivided, then address subdivision
constraints.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#subdiv-constraints-
principle
YES/NO/Not Applicable: Explain why?
Not Applicable
See 4.1.B
4.3.A: Address Extensibility.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#likehood-extension-
principle
YES/NO/Not Applicable: Explain why?
NO
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.
4.4.A: Identify deprecated features.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#deprecated-feature-
principle
YES/NO/Not Applicable: Explain why?
Not Applicable
There's no previous version of this document.
4.4.B: Define how deprecated feature is handled by each class of
product.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#degree-support-
principle
YES/NO/Not Applicable: Explain why?
Not Applicable
See 4.4.A
=====================================
* 25 Good Practices (Not normative) *
=====================================
1.1.B: Define the specification's conformance model in the conformance
clause.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#conformance-model-gp
YES/NO/Not Applicable: Explain why?
1.1.C: Specify in the conformance clause how to distinguish normative
from informative content.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#norm-informative-gp
YES/NO/Not Applicable: Explain why?
1.2.A: Provide the wording for conformance claims.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#conformance-claim-gp
YES/NO/Not Applicable: Explain why?
1.2.B: Provide an Implementation Conformance Statement proforma.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#ics-gp
YES/NO/Not Applicable: Explain why?
1.2.C: Require an Implementation Conformance Statement as part of valid
conformance claims.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#ics-claim-gp
YES/NO/Not Applicable: Explain why?
2.1.B: Provide examples, use cases, and graphics.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#use-example-gp
YES/NO/Not Applicable: Explain why?
2.3.B: Do systematic reviews of normative references and their
implications.
http://w3c.test.site/TR/2004/WD-qaframe-spec-20041122/#ref-define-
practice
YES/NO/Not Applicable: Explain why?
3.1.C: Define the unfamiliar terms in-line, and consolidate the
definitions in a glossary section.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#define-terms-
inline-gp
YES/NO/Not Applicable: Explain why?
3.1.D: Use terms already defined without changing their definition.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#reuse-terms-gp
YES/NO/Not Applicable: Explain why?
4.1.A: Create subdivisions of the technology when warranted.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#subdivide-foster-gp
YES/NO/Not Applicable: Explain why?
4.1.D: If the technology is profiled, define rules for creating new
profiles.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#rules-profiles-gp
YES/NO/Not Applicable: Explain why?
4.2.A: Make sure there is a need for the optional feature.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#need-option-gp
YES/NO/Not Applicable: Explain why?
4.2.B: Clearly identify optional features.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#label-options-gp
YES/NO/Not Applicable: Explain why?
4.2.C: Indicate any limitations or constraints on optional features.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#constraints-gp
YES/NO/Not Applicable: Explain why?
4.3.B: If extensibility is allowed, define an extension mechanism.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#extensions-
prohibited-gp
YES/NO/Not Applicable: Explain why?
4.3.C: Warn implementers to create extensions that do not interfere
with conformance.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#breaking-
conformance-gp
YES/NO/Not Applicable: Explain why?
4.3.D: Define error handling for unknown extensions.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#define-error-gp
YES/NO/Not Applicable: Explain why?
4.4.C: Explain how to avoid using a deprecated feature.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#workaround-gp
YES/NO/Not Applicable: Explain why?
4.4.D: Identify obsolete features.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#obsolete-gp
YES/NO/Not Applicable: Explain why?
4.5.A: Define an error handling mechanism.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#error-handling-gp
YES/NO/Not Applicable: Explain why?
5.A: Define an internal publication and review process.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#practice-principle
YES/NO/Not Applicable: Explain why?
5.B: Do a systematic and thorough review.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#review-gp
YES/NO/Not Applicable: Explain why?
5.C: Write sample code or tests.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#write-sample-gp
YES/NO/Not Applicable: Explain why?
5.D: Write Test Assertions.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#write-assertion-gp
YES/NO/Not Applicable: Explain why?
5.E: Use formal languages and define which from prose and formal
languages has priority.
http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#formal-language-gp
YES/NO/Not Applicable: Explain why?
--
Karl Dubost - http://www.w3.org/People/karl/
W3C Conformance Manager
*** Be Strict To Be Cool ***
Received on Wednesday, 8 December 2004 22:48:36 UTC