W3C home > Mailing lists > Public > public-rdf-dawg-comments@w3.org > October 2005

[comments] SPARQL Protocol against QA SpecGL ICS

From: Karl Dubost <karl@w3.org>
Date: Tue, 11 Oct 2005 18:17:44 -0400
Message-Id: <5F16A7AC-7CEB-481F-AC2B-9127616589B5@w3.org>
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 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Tuesday, 8 January 2008 14:14:49 GMT