- From: Karl Dubost <karl@w3.org>
- Date: Thu, 19 May 2005 16:32:17 -0400
- To: public-esw-thes@w3.org
Hi, This is review of SKOS Core Vocabulary Specification http://www.w3.org/TR/2005/WD-swbp-skos-core-spec-20050510/ against QA Specification Guidelines http://www.w3.org/TR/2005/WD-qaframe-spec-20050428/ We acknowledge the fact that SKOS Core Vocabulary is a first publication and then has not reached the level of maturity that would be expected on a Last Call Specification. We believe if you keep in mind QA Specification Guidelines, it well the WG to identify issues and have a specification that should be easier to implement. Follows the list of Good Practices, I'm not checking your specification against them for now, but it's good to try to do as much as possible of them. If you need help or you have questions, the QA WG is at your disposition for the time being. Best Regards I have taken the ICS of QA Specification Guidelines to evaluate your document. http://www.w3.org/TR/2005/qaframe-spec/specgl-ics List of Requirements: Requirement 01: Include a conformance clause. NO. There's none. Requirement 02: Define the scope. YES. Introduction of your document has elements for a scope section. Please make it a subsection of your introduction and call it "Scope" Requirement 03: Identify who and/or what will implement the specification. NO. Not defined. This is very important to define because it will help to design the conformance model of your specification. Requirement 04: Make a list of normative references. NO. Please do it, even at the early stage of your specification. It will help reviewers to track conflicts with other technologies if any. Requirement 05: Define the terms used in the normative parts of the specification. NO. All the terms are not defined as recommended by QA Specification Guidelines. Requirement 06: Create conformance labels for each part of the conformance model. NO. It might be a bit early to do so, but start to think about it. Answering the Requirement 03 will help to do it. Requirement 07: Use a consistent style for conformance requirements and explain how to distinguish them. NO. Having no conformance section, it's impossible to know what is mandatory, what is optional. Requirement 08: Indicate which conformance requirements are mandatory, which are recommended, and which are optional. NO. No conformance section. Requirement 09: If the technology is subdivided, then indicate which subdivisions are mandatory for conformance. N/A. The technology seems to be monolithic without subdivisions for now. Requirement 10: If the technology is subdivided, then address subdivision constraints. N/A. Same as Requirement 09. Requirement 11: Address Extensibility. NO. The topic is not addressed. It's very important to do so, specifically in the context of your application. Requirement 12: Identify deprecated features. N/A. It seems that there's none being the first version of your technology. Requirement 13: Define how each class of product handles each deprecated feature. N/A. See Requirement 12. List of Good Practices: Good Practice 01: Define the specification's conformance model in the conformance clause. Good Practice 02: Specify in the conformance clause how to distinguish normative from informative content. Good Practice 03: Provide the wording for conformance claims. Good Practice 04: Provide an Implementation Conformance Statement Pro Forma. Good Practice 05: Require an Implementation Conformance Statement as part of valid conformance claims. Good Practice 06: Provide examples, use cases, and graphics. Good Practice 07: Write sample code or tests. Good Practice 08: When imposing requirements by normative references, address conformance dependencies. Good Practice 09: Define unfamiliar terms in-line and consolidate the definitions in a glossary section. Good Practice 10: Use terms already defined without changing their definition. Good Practice 11: Use formal languages when possible. Good Practice 12: Write Test Assertions. Good Practice 13: Create subdivisions of the technology when warranted. Good Practice 14: If the technology is profiled, define rules for creating new profiles. Good Practice 15:Use optional features as warranted. Good Practice 16: Clearly identify optional features. Good Practice 17: Indicate any limitations or constraints on optional features. Good Practice 18: If extensibility is allowed, define an extension mechanism. Good Practice 19: Warn extension creators to create extensions that do not interfere with conformance. Good Practice 20: Define error-handling for unknown extensions. Good Practice 21: Explain how to avoid using a deprecated feature. Good Practice 22: Identify obsolete features. Good Practice 23: Define an error handling mechanism. -- Karl Dubost - http://www.w3.org/People/karl/ W3C Conformance Manager *** Be Strict To Be Cool ***
Received on Thursday, 19 May 2005 20:32:22 UTC