Manual to edit The QA Matrix

The Matrix is a page which gives information about the W3C specifications, featuring a synthetic table with information useful for specification implementors. At first, it was managed using an XML vocabulary, but is now managed using an RDF system, allowing both a better design of the semantics involved and an easier maintenance, relying on the Technical Reports Management Automation.

This document describes the process and steps involved in the maintenance of this document.

Overview of the process

The Matrix is maintained by adding any new information received on a given technical report to an existing base of knowledge formatted in Notation3 (N3), an easy-to-write syntax for RDF. This knowledge base uses a specially crafted RDF Schema.

This knowledge base is then merged with the base of knowledge about W3C Technical Reports, maintained by the Webmaster, to generate an RDF view of the Matrix, which is then transformed into its main XHTML view through XSLT.

How to Update The Matrix

Prerequisites

To manage the Matrix, you need the following tools installed on your system:

cwm, a general-purpose data processor for the semantic web (see the detailed installation procedure, which requires to have a working version of Python, version 2.2 or greater)
a compliant XSLT processor (the one used as example below is xsltproc, although any other XSLT processor can be used in its stead
for ease of use (but not required), the make utility installed
a recent version of PyXML

Besides, you need to have the following data (publicly accessible on the W3C site) on your filesystem, in a hierarchy similar to the one used on the site:

The list of W3C Technical Reports in RDF
The knowledge base on Quality Assurance information for the W3C Technical Reports in N3
The rules used to identify the Technical Reports relevant to the Matrix
The filtering rules to keep only relevant data from the two previous lists
The XSLT style sheet used to create the XHTML version from the RDF one
optionally, the Makefile that allows to manage automatically most of the steps

Besides, it is necessary that the maintainer has a basic understanding of the N3 syntax.

Updating the knowledge base

To update the knowledge base, simply add at the end of the file a line such as <http://www.w3.org/TR/qaframe-spec/> :hasConformanceSection <http://www.w3.org/TR/qaframe-spec/#conformance>. (the first URI being the latest version URI of the said specification, the :hasConformanceSection one of the property defined in the schema, and the second URI the object of this property.

Updating the RDF Version

Once the knowledge base updated (or if you want to bring the Matrix up to date with regard to the Technical Reports list), use the following command line: cwm QA/2002/10/merge-tr-matrix.n3 --think QA/2002/10/matrix-base.n3 --rdf 2002/01/tr-automation/tr.rdf --filter=QA/2002/10/filter-matrixdata.n3 --rdf > QA/TheMatrix.rdf (or simply use the relevant Makefile rule).

This command line has for effect to:

load the 2 knowledge bases and identify in them the relevant Technical Reports (done by merge-tr-matrix.n3)
merge the 2 knowledge bases
filter the merged output to only keep relevant data about relevant Technical Reports (done by --filter=QA/2002/10/filter-matrixdata.n3)
put the output in TheMatrix.rdf

The XHTML version

Never edit directly the file /QA/TheMatrix.html. This file is created when you run the xsl stylesheet.

The command to run the xslt stylesheet is (as described in the Makefile: xsltproc QA/TheMatrix.rdf QA/2002/10/toMatrix.xsl > QA/TheMatrix.html

Vocabulary used in the N3 Knowledge base

The knowledge base uses a specially crafted RDF Schema in a Notation3 syntax. While this schema is self-describing (and human readable through a client-side XSLT if your user agent supports it), this document quickly describes its most important properties (assuming that the mat prefix is bound to http://www.w3.org/2002/05/matrix/vocab# namespace):

mat:hasConformanceSection: points to the conformance section of the given specification
mat:hasErrata: points to the list of the known errata for the given specification
mat:hasFeedbackML: points to the archives of a mailing list used to comment on the specification
mat:hasImplReport: point to the implementation report of the specification
mat:hasInteropReport: point to the interoperability report of the specification
mat:hasLCIssues: points to the maintained list of Last Call issues for the specification
mat:hasRequirements: points to a document gathering the requirements on which the specification is built
mat:hasTestSuite: points to a description of an existing test suite that can be used to test the implementation of the specification
mat:hasTranslations: points to the list of known translations for the specification
mat:hasValidator: points to a validation service for the specification

Besides these properties, the knowledge base uses vocabulary from the Dublin Core Schema, used to describe simple bibliographic data.

Benefits of the RDF-management of the Matrix

The fact that the Matrix is now managed through an RDF vocabulary, and more generally with Semantic-Web enabled technologies bring the following benefits:

the synchronization with the data maintained by the W3C Webmaster about the Technical Reports doesn't need any human intervention any more
the data in RDF can easily be integrated in other Semantic Web projects; for instance, the list of known errata has been integrated in the TR page, and the data are going to be incorporated in the experimental TAP search service
the RDF vocabulary models real-life objects (hence a better modeling), and is self-describing
it will possible to generate easily reports of missing or inconsistent data, thanks to the richer semantics brought by the vocabulary, and the rules defining the W3C process

For more details on this topic, see why we're using RDF to manage the matrix.