- From: Karl Dubost <karl@w3.org>
- Date: Tue, 11 Oct 2005 18:17:44 -0400
- To: public-rdf-dawg-comments@w3.org
This is a review of "SPARQL Protocol" against QA SpecGL ICS.
SPARQL Protocol for RDF
W3C Working Draft 14 September 2005
http://www.w3.org/TR/2005/WD-rdf-sparql-protocol-20050914/
First of all, I'm unpleasantly surprised that there is no conformance
section in the document nor a reference to a document where this
conformance would be defined. I thought it was now a common practice
from all WGs. It seems not, we will need to be more careful in the
future.
In the following list,
Requirements are mandatory
Good Practices are optional
I haven't been through the list of Good Practices, because the
document is quite bad on a QA side. You failed 5 Requirements of QA
Spec GL.
It seems that SPARQL Query, that I should have reviewed too, is in
bad shape too. If you think it's still time, I might do it as the two
documents work together.
# QA Specification Guidelines - Implementation Conformance Statement
This version: [http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/
specgl-ics][3]
## Checklist table
[Requirement 01: Include a conformance clause.][22]
NO and no reference to a document which would contain such a
section.
[Requirement 02: Define the scope.][29]
YES. but very little one. The scope section could be a little
more detailed. Look at the techniques.
[Requirement 03: Identify who and/or what will implement the
specification.][32]
NO. The "classes of products" are not identified, which will
make it difficult to create a conformance clause.
[Requirement 04: Make a list of normative references. ][33]
YES. Be careful 4 of your normative references are not yet
Recommendations. It means that this document will not be able to
become a REC before they are or at least at the same time they become
REC themselves.
[Requirement 05: Define the terms used in the normative parts of the
specification.][36]
YES. The terms seem to be defined along the text but it's not
obvious when it's a definition or when it's a simple explanation. A
consolidated glossary would help.
[Requirement 06: Create conformance labels for each part of the
conformance model.][37]
NO. The conformance section is not defined.
[Requirement 07: Use a consistent style for conformance requirements
and explain how to distinguish them.][40]
YES. you are using the RFC2119 keywords in the document to
define your requirements. Though be careful sometimes, you are using
a double requirement in the same sentence which might lead to
misunderstanding. For example, in 2.1.4 "Any message after the first
in the pattern may be replaced with a fault message, which must have
identical direction."
Sometimes you are using may and it's not sure in which context.
For example "The QueryRequestRefused fault message does not indicate
whether the server may or may not process a subsequent, identical
request or requests." is not in bold. To avoid this kind of
situation, we recommend in QA guidelines to avoid the use of
normative prose when it's not intented to be.
[Requirement 08: Indicate which conformance requirements are
mandatory, which are recommended, and which are optional.][41]
NO. if we consider the fact you are using RFC 2119, we could
say yes, but there's also the fact that you do not define which
sections in your document is normative or not normative.
[Requirement 09: If the technology is subdivided, then indicate which
subdivisions are mandatory for conformance.][46]
N/A. Your technology doesn't seem to be modular, or have levels
or profiles.
[Requirement 10: If the technology is subdivided, then address
subdivision constraints.][47]
N/A.
[Requirement 11: Address Extensibility.][52]
NO. This has not been addressed at all. Create a section on
extensibility and explain the extensibility, requirements or your
language. If it's not extensible, say it. (As a side comment,
extensibility as it is defined in QA, not TAG ;) to avoid
misunderstanding)
[Requirement 12: Identify deprecated features.][56]
N/A. As it is the first publication, it is considered that there
is none.
[Requirement 13: Define how each class of product handles each
deprecated feature.][57]
N/A.
## List of Good Practices for references.
[Good Practice 01: Define the specification's conformance model in
the conformance clause.][23]
[Good Practice 02: Specify in the conformance clause how to
distinguish normative from informative content.][24]
[Good Practice 03: Provide the wording for conformance claims.][25]
[Good Practice 04: Provide an Implementation Conformance Statement
Pro Forma.][26]
[Good Practice 05: Require an Implementation Conformance Statement as
part of conformance claims.][27]
[Good Practice 06: Provide examples, use cases, and graphics.][30]
[Good Practice 07: Write sample code or tests.][31]
[Good Practice 08: When imposing requirements by normative
references, address conformance dependencies.][34]
[Good Practice 09: Define unfamiliar terms in-line and consolidate
the definitions in a glossary section.][38]
[Good Practice 10: Use terms already defined without changing their
definition.][39]
[Good Practice 11: Use formal languages when possible.][42]
[Good Practice 12: Write Test Assertions.][43]
[Good Practice 13: Create subdivisions of the technology when
warranted.][45]
[Good Practice 14: If the technology is profiled, define rules for
creating new profiles.][48]
[Good Practice 15:Use optional features as warranted.][49]
[Good Practice 16: Clearly identify optional features.][50]
[Good Practice 17: Indicate any limitations or constraints on
optional features.][51]
[Good Practice 18: If extensibility is allowed, define an extension
mechanism.][53]
[Good Practice 19: Warn extension creators to create extensions that
do not interfere with conformance.][54]
[Good Practice 20: Define error-handling for unknown extensions.][55]
[Good Practice 21: Explain how to avoid using a deprecated feature.][58]
[Good Practice 22: Identify obsolete features.][59]
[Good Practice 23: Define an error handling mechanism.][60]
[21]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/
#specifying-conformance
[22]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/
#include-conformance-clause-principle
[23]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/
#conformance-model-gp
[24]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/#norm-
informative-gp
[25]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/
#conformance-claim-gp
[26]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/#ics-gp
[27]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/#ics-
claim-gp
[28]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/#nature
[29]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/#define-
scope-principle
[30]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/#use-
example-gp
[31]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/#write-
sample-gp
[32]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/
#implement-principle
[33]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/#ref-
norm-principle
[34]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/#ref-
define-practice
[35]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/
#specify-conformance-need
[36]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/#define-
terms-principle
[37]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/#conf-
label-principle
[38]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/#define-
terms-inline-gp
[39]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/#reuse-
terms-gp
[40]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/
#consistent-style-principle
[41]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/#req-
opt-conf-principle
[42]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/#formal-
language-gp
[43]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/#write-
assertion-gp
[44]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/
#variability
[45]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/
#subdivide-foster-gp
[46]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/
#subdivide-mandatory-principle
[47]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/#subdiv-
constraints-principle
[48]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/#rules-
profiles-gp
[49]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/#need-
option-gp
[50]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/#label-
options-gp
[51]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/
#constraints-gp
[52]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/
#likehood-extension-principle
[53]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/
#extensions-prohibited-gp
[54]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/
#breaking-conformance-gp
[55]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/#define-
error-gp
[56]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/
#deprecated-feature-principle
[57]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/#degree-
support-principle
[58]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/
#workaround-gp
[59]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/
#obsolete-gp
[60]: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/#error-
handling-gp
--
Karl Dubost - http://www.w3.org/People/karl/
W3C Conformance Manager
*** Be Strict To Be Cool ***
Received on Wednesday, 12 October 2005 02:06:03 UTC