This is a review of
[[[
Network Working Group M. Nottingham, Ed.
Internet-Draft R. Sayre, Ed.
Expires: October 20, 2005 April 18, 2005
The Atom Syndication Format
draft-ietf-atompub-format-08
]]] -
http://ietf.levkowetz.com/drafts/atompub/format/draft-ietf-atompub-
format-08.txt
against W3C QA Framework: Specification Guidelines.
http://www.w3.org/TR/qaframe-spec/
(A new version of Specification Guidelines will be published next
week in Proposed Recommendation. This review has been made with the
Editor's draft version which is not public yet).
Short Intro:
W3C QA Specification Guidelines has been designed to help W3C editors
write better specifications. It focuses on how to define and specify
conformance for a specification. Additionally, it addresses how a
specification might allow variation among conforming implementations.
I have done the review of Atom 0.8 to test W3C QA Specification
Guidelines with an external technical document and I thought it could
be also useful to the Atom community.
The QA Specification Guidelines Specification is organized with a
series of mandatory "Requirements" and optional "Good Practices". For
each of them, you will find an explanation and a benefits analysis,
plus techniques, examples, and other readings.
You might want to read the Test FAQ too.
http://www.w3.org/QA/WG/2005/01/test-faq
to create a test suite for Atom and shared between developers
http://intertwingly.net/wiki/pie/ConformanceTests
Best Regards.
Requirement 01: Include a conformance clause.
NO. There is indeed a section which is an attempt of conformance
clause but doesn't fulfill all the requirements that we could expect
from such sections. It would be good to have a specific table of
content item with the words conformance to help developers to
understand right away the conformance model of the specification.
Requirement 02: Define the scope.
YES. In the introduction of the document are given what the
technology is about. Though it could be certainly improved, by giving
a more systemic way of describing the scope.
Requirement 03: Identify who or what will implement the specification.
NO. For example, we can see "Atom Processors" in the
specification, but it is defined what's an atom processor. The list
of class of products would help to define the conformance model, and
then the conformance clause. What about authoring tools? What about
validators? etc.
Requirement 04: Make a list of normative references.
YES. The list of normative references is given.
Requirement 05: Define the terms used in the normative parts of the
specification.
NO. "Atom Processors" is not defined. Atom Feed is defined, Atom
Entry as well. Some of the important concept really need more
definitions. It's really important because it avoids broad
interpretation of some terms.
Requirement 06: Create conformance labels for each part of the
conformance model.
NO. The conformance model being not completely clear. It's very
hard to know what are the different type of conformance and then to
put labels on them.
Requirement 07: Use a consistent style for conformance requirements
and explain how to distinguish them.
YES. the RFC is using a consistent style explained in Notational
conventions.
Requirement 08: Indicate which conformance requirements are
mandatory, which are recommended, and which are optional.
YES/NO. Because of the lack of conformance clause clearly
defined, it might be confusing. For example "This specification does
not define a DTD for Atom Documents, and hence does not require them
to be valid (in the sense used by XML)." But a document could be
valid against the RELAXNG Schema. Is there any reason to not make the
schema normative?
Requirement 09: If the technology is subdivided, then indicate which
subdivisions are mandatory for conformance.
N/A. The technology seems to not be modular and then not
subdivided.
Requirement 10: If the technology is subdivided, then address
subdivision constraints.
N/A.
Requirement 11: Address Extensibility.
YES. Perfectly addressed.
Requirement 12: Identify deprecated features.
N/A. None.
Requirement 13: Define how each class of product handles each
deprecated feature.
N/A. None.
List of Good Practices (OPTIONAL):
Good Practice 01: Define the specification's conformance model in the
conformance clause.
NO.
Good Practice 02: Specify in the conformance clause how to
distinguish normative from informative content.
NO.
Good Practice 03: Provide the wording for conformance claims.
NO.
Good Practice 04: Provide an Implementation Conformance Statement Pro
Forma.
NO.
Good Practice 05: Require an Implementation Conformance Statement as
part of valid conformance claims.
NO.
Good Practice 06: Provide examples, use cases, and graphics.
YES.
Good Practice 07: Write sample code or tests.
YES.
Good Practice 08: When imposing requirements by normative references,
address conformance dependencies.
YES.
Good Practice 09: Define unfamiliar terms in-line and consolidate the
definitions in a glossary section.
NO.
Good Practice 10: Use terms already defined without changing their
definition.
YES.
Good Practice 11: Use formal languages when possible.
NO. You have used a formal language, the RelaxNG Schema but you
didn't make it normative.
Good Practice 12: Write Test Assertions.
NO.
Good Practice 13: Create subdivisions of the technology when warranted.
N/A.
Good Practice 14: If the technology is profiled, define rules for
creating new profiles.
N/A.
Good Practice 15:Use optional features as warranted.
YES. It seems it has been clearly defined when something is
optional when it's not.
Good Practice 16: Clearly identify optional features.
YES. but could be better.
Good Practice 17: Indicate any limitations or constraints on optional
features.
YES.
Good Practice 18: If extensibility is allowed, define an extension
mechanism.
YES. A whole section is dedicated to it.
Good Practice 19: Warn extension creators to create extensions that
do not interfere with conformance.
NO.
Good Practice 20: Define error-handling for unknown extensions.
YES.
Good Practice 21: Explain how to avoid using a deprecated feature.
N/A.
Good Practice 22: Identify obsolete features.
N/A.
Good Practice 23: Define an error handling mechanism.
YES.
--
Karl Dubost - http://www.w3.org/People/karl/
W3C Conformance Manager
*** Be Strict To Be Cool ***
